JIRA MCP Integration

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

Features

Create JIRA tickets with summary, description, acceptance criteria, and issue type
Assign story points to Story tickets
Automatically create linked Test tickets for Stories with points
Seamless integration with Claude desktop application
Simple configuration using Claude's desktop configuration file

Installation

Clone the repository:

git clone https://github.com/MankowskiNick/jira-mcp.git
cd jira-mcp

Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```

Configuration

Claude Desktop Configuration

Add the JIRA MCP server configuration to your claude_desktop_config.json file. This file is typically located at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Roaming\Claude\claude_desktop_config.json

Add the following configuration to the file:

{
  "mcpServers": {
    "jira-mcp": {
      "command": "node",
      "args": ["/path/to/project/build/index.js"],
      "env": {
        "JIRA_HOST": "your-site.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "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"
      }
    }
  }
}

Replace the placeholder values with your actual JIRA information:

/path/to/project/build/index.js: Full path to the built index.js file
JIRA_HOST: Your JIRA instance domain (e.g., company.atlassian.net)
JIRA_USERNAME: Your JIRA username (usually your email address)
JIRA_API_TOKEN: Your JIRA API token (see below for how to get this)
JIRA_PROJECT_KEY: The key for your JIRA project (e.g., SCRUM, DEV, etc.)
AUTO_CREATE_TEST_TICKETS: Set to "true" (default) to automatically create linked Test tickets for Story tickets with points, or "false" to disable this feature

Custom Field Configuration

The following environment variables allow you to configure custom fields without hardcoding them in the source code:

JIRA_ACCEPTANCE_CRITERIA_FIELD: The field ID for acceptance criteria (default: "customfield_10429")
JIRA_STORY_POINTS_FIELD: The field ID for story points (default: "customfield_10040")
JIRA_EPIC_LINK_FIELD: The field ID for epic links (default: "customfield_10014")

Product Field Configuration (Optional)

JIRA_PRODUCT_FIELD: The field ID for the product field
JIRA_PRODUCT_VALUE: The display value for the product
JIRA_PRODUCT_ID: The ID of the product option

Category Field Configuration (Optional)

JIRA_CATEGORY_FIELD: The field ID for the category field
USE_ALTERNATE_CATEGORY: Set to "true" to use alternate category, "false" for default
JIRA_DEFAULT_CATEGORY_VALUE: The display value for the default category
JIRA_DEFAULT_CATEGORY_ID: The ID of the default category option
JIRA_ALTERNATE_CATEGORY_VALUE: The display value for the alternate category
JIRA_ALTERNATE_CATEGORY_ID: The ID of the alternate category option

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, or Story, 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")

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

read-ticket

Retrieves the details of an existing JIRA ticket. Parameters:

ticket_id: The ID of the JIRA ticket you want to read (required)

Usage with Claude

Once configured properly, you can ask Claude to create JIRA tickets directly:

Please create a JIRA ticket to track the database performance issue we discussed.

You can also specify acceptance criteria for your tickets:

Create a JIRA ticket for implementing the new user authentication feature with the following acceptance criteria:
- Users can log in with email and password
- Password reset functionality works via email
- Account lockout occurs after 5 failed attempts
- OAuth integration with Google and Facebook

Claude will use the create-ticket tool to generate a ticket in your JIRA project with all the specified details.

Getting a JIRA API Token

Log in to your Atlassian account at https://id.atlassian.com/manage-profile/security
Go to Security > API tokens
Click "Create API token"
Give your token a name (e.g., "Claude Integration")
Click "Create"
Copy the token (you won't be able to see it again)

Troubleshooting

If you encounter issues:

Check that your JIRA credentials are correct
Verify the path to the project's index.js file in your claude_desktop_config.json
Make sure you've given Claude permission to use tools
Check Claude's console logs for any error messages related to the JIRA MCP server