A Model Context Protocol server for integrating JIRA with Claude. This tool allows Claude to create JIRA tickets directly within your conversations.

Overview

The JIRA MCP project is a Node.js/TypeScript application that provides a Model Context Protocol (MCP) server for integrating with JIRA and Zephyr. It allows AI assistants to interact with JIRA for project management and Zephyr for test management through a standardized protocol.

Features

Create JIRA tickets with summary, description, acceptance criteria, and issue type
Search JIRA tickets using flexible JQL queries or by issue type
Assign story points to Story tickets
Automatically create linked Test tickets for Stories with points
Enhanced error handling with automatic retry for custom field validation issues
Updated to use latest JIRA REST API v3 specification (CHANGE-2046 compliant)
Search for JIRA tickets by issue type and additional criteria
Update existing JIRA tickets with new field values
Link JIRA tickets together with specified relationship types
Retrieve and add test steps for Zephyr test tickets
Seamless integration with Claude desktop application
Simple configuration using Claude's desktop configuration file

Configuration

Configuration Template

A template configuration file has been provided in jira-mcp-config-template.json. This template shows all possible configuration options for the JIRA MCP server.

Basic Configuration

Add the following configuration to your Claude configuration file:

            
{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["/path/to/project/build/index.js"],
      "env": {
        "JIRA_HOST": "your-site.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_PROJECT_KEY": "your_project_key",
        "AUTO_CREATE_TEST_TICKETS": "true",

        "JIRA_ACCEPTANCE_CRITERIA_FIELD": "customfield_10429",
        "JIRA_STORY_POINTS_FIELD": "customfield_10040",
        "JIRA_EPIC_LINK_FIELD": "customfield_10014",

        "JIRA_PRODUCT_FIELD": "customfield_10757",
        "JIRA_PRODUCT_VALUE": "Your Product Name",
        "JIRA_PRODUCT_ID": "12345",

        "JIRA_CATEGORY_FIELD": "customfield_10636",
        "USE_ALTERNATE_CATEGORY": "false",
        "JIRA_DEFAULT_CATEGORY_VALUE": "Default Category",
        "JIRA_DEFAULT_CATEGORY_ID": "12345",
        "JIRA_ALTERNATE_CATEGORY_VALUE": "Alternate Category",
        "JIRA_ALTERNATE_CATEGORY_ID": "67890"
      }
    }
  }
}

Minimal Configuration Example

If you want the absolute minimal configuration, you can use:

            
{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "your-site.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_PROJECT_KEY": "your_project_key"
      }
    }
  }
}

Available Tools

create-ticket

Creates a new JIRA ticket.

Parameters:

summary: The title/summary of the ticket (required)
issue_type: The type of issue (Bug, Task, Story, or Test, defaults to Task)
description: Detailed description of the ticket (optional)
acceptance_criteria: Acceptance criteria for the ticket (optional, stored in customfield_10429)
story_points: Story points for the ticket (optional, Fibonacci sequence: 1, 2, 3, 5, 8, 13, etc.)
create_test_ticket: Override the default setting for automatically creating a linked Test ticket (optional, boolean)
parent_epic: Key of the parent epic to link this ticket to (optional, e.g., PROJ-123)
sprint: The name of the sprint to assign the ticket to (optional, e.g., 2025_C1_S07)
story_readiness: Whether the story is ready for development (optional, Yes or No)
crisis: Whether this ticket represents a crisis/urgent issue (optional, Yes or No)

When creating a Story ticket with story points:

The QA-Testable label is automatically added to the Story
A linked Test ticket is automatically created (if AUTO_CREATE_TEST_TICKETS is enabled)
The Test ticket uses the Story's title as its description
The Test ticket is linked to the Story with a Test Case Linking relationship

Example:

{ "summary": "Implement user authentication feature", "issue_type": "Story", "description": "As a user, I want to be able to log in to the application", "acceptance_criteria": "- Users can log in with email and password\n- Password reset functionality works via email", "story_points": 5, "parent_epic": "PROJ-100", "sprint": "2025_C1_S07", "story_readiness": "Yes" }

get-ticket

Retrieves the details of an existing JIRA ticket.

Parameters:

ticket_id: The ID/key of the JIRA ticket you want to read (required, e.g., PROJ-123)

Example:

{ "ticket_id": "PROJ-123" }

The response includes all fields of the ticket, including custom fields.

search-tickets

Searches for JIRA tickets by issue type and additional criteria.

Parameters:

issue_type: The type of issue to search for (Bug, Task, Story, or Test) (required)
max_results: Maximum number of results to return (optional, default: 10, max: 50)
additional_criteria: Additional JQL criteria to include in the search (optional)

Example:

{ "issue_type": "Bug", "max_results": 20, "additional_criteria": "status = 'Open' AND priority = 'High'" }

This tool allows you to find all tickets of a specific type in your JIRA project. You can further refine your search by providing additional JQL criteria.

update-ticket

Updates an existing JIRA ticket with new field values.

Parameters:

ticket_key: The key of the JIRA ticket to update (required, e.g., PROJ-123)
sprint: The name of the sprint to assign the ticket to (optional, e.g., 2025_C1_S07)
story_readiness: Whether the story is ready for development (optional, Yes or No)

Example:

{ "ticket_key": "PROJ-123", "sprint": "2025_C1_S07", "story_readiness": "Yes" }

This tool allows you to update existing tickets with sprint information and story readiness status. At least one field must be provided for the update to proceed.

link-tickets

Links two JIRA tickets together with a specified relationship type.

Parameters:

outward_issue: The key of the outward issue (required, e.g., PROJ-123)
inward_issue: The key of the inward issue (required, e.g., PROJ-456)
link_type: The type of link to create (optional, defaults to Test Case Linking)

Example:

{ "outward_issue": "PROJ-123", "inward_issue": "PROJ-456", "link_type": "Blocks" }

This creates a link between two tickets with the specified relationship type. For example, PROJ-123 blocks PROJ-456.

get-test-steps

Retrieves test steps from a Zephyr test ticket.

Parameters:

ticket_key: The key of the test ticket to retrieve steps from (required, e.g., PROJ-123)

Example:

{ "ticket_key": "PROJ-123" }

This tool retrieves all test steps associated with a test ticket in Zephyr. The response includes the step description, test data, and expected result for each step.

add-test-steps

Adds test steps to a test ticket via the Zephyr integration.

Parameters:

ticket_key: The key of the test ticket to add steps to (required, e.g., PROJ-123)
steps: An array of test step objects (required), where each step object contains:
- step: The description of the test step (required)
- data: Test data for the step (optional)
- result: Expected result of the step (optional)

Example:

{ "ticket_key": "PROJ-123", "steps": [ { "step": "Navigate to the login page", "data": "https://example.com/login", "result": "Login form is displayed" }, { "step": "Enter valid credentials", "data": "username=test, password=password123", "result": "User is logged in successfully" } ] }

This tool requires Zephyr for Jira Cloud to be installed and configured. You'll need to set the Zephyr API environment variables in your configuration file.