Jira MCP Server

A Model Context Protocol (MCP) server for Jira API integration. This server enables AI assistants like Claude to interact with Jira Cloud instances for issue management, search, comments, and workflow transitions.

Features

• Issue Management: Get, create, update, and assign Jira issues with custom field support
• JQL Search: Search issues using Jira Query Language
• Comments: Add and retrieve comments on issues (supports mentions and links)
• Workflow: Get available transitions and change issue status
• Metadata Discovery: Get field requirements and allowed values for projects
• User Search: Find users by email or name for assignments
• Projects: List all accessible projects
• API Token Authentication: Secure authentication using email + API token

Installation

Using npm (Recommended)

npm install -g @nexus2520/jira-mcp-server

From Source

1. Clone the repository:

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

2. Install dependencies:

   pnpm install
   

3. Build the project:

   pnpm run build
   

Prerequisites

• Node.js >= 16.0.0
• A Jira Cloud account with API access
• Jira API token (generate from Atlassian Account Settings)

Configuration

Environment Variables

The server requires the following environment variables:

• JIRA_EMAIL: Your Atlassian account email
• JIRA_API_TOKEN: Your Jira API token
• JIRA_BASE_URL: Your Jira instance URL (e.g., https://yourcompany.atlassian.net)

Claude Desktop Configuration

Add the following to your Claude Desktop MCP settings file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Configuration (if installed via npm):

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": [
        "-y",
        "@nexus2520/jira-mcp-server"
      ],
      "env": {
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token-here",
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net"
      }
    }
  }
}

Configuration (if built from source):

{
  "mcpServers": {
    "jira": {
      "name": "jira",
      "command": "node",
      "args": [
        "/absolute/path/to/jira-mcp-server/build/index.js"
      ],
      "transport": "stdio",
      "env": {
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token-here",
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net"
      }
    }
  }
}

Getting Your Jira API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label (e.g., "Claude MCP")
4. Copy the generated token
5. Use it in your configuration

Available Tools

Issue Management

get_issue

Get detailed information about a Jira issue.

Parameters:

• issueKey (required): The issue key (e.g., "PROJ-123")

Example:

Get details for issue PROJ-123

create_issue

Create a new Jira issue.

Important: Always use get_create_metadata first to discover required fields, custom fields, and allowed values.

Parameters:

• projectKey (required): Project key (e.g., "PROJ", "DEV")
• summary (required): Issue title
• issueType (required): Type (e.g., "Bug", "Task", "Story")
• description (optional): Issue description
• priority (optional): Priority name
• assignee (optional): Assignee account ID or email
• labels (optional): Array of labels
• customFields (optional): Custom fields object

Example:

Create a bug in project PROJ with summary "Login button not working" and description "Users cannot log in"

update_issue

Update fields of an existing issue.

Tip: Use get_create_metadata to discover available custom fields and their allowed values.

Parameters:

• issueKey (required): Issue to update
• summary (optional): New summary
• description (optional): New description
• priority (optional): New priority
• assignee (optional): New assignee
• labels (optional): New labels array
• customFields (optional): Custom fields object

assign_issue

Assign an issue to a user.

Parameters:

• issueKey (required): Issue to assign
• assignee (required): User account ID, email, or "-1" to unassign

Metadata & Discovery

get_create_metadata

Get field requirements and metadata for creating issues in a project.

Parameters:

• projectKey (required): Project key
• issueType (optional): Filter by specific issue type

search_users

Search for users by name or email to get their account ID.

Parameters:

• query (required): Search query (email or name)
• maxResults (optional): Max results (default: 50)

Search

search_issues

Search for issues using JQL. Returns issue keys and titles.

Parameters:

• jql (required): JQL query string
• maxResults (optional): Max results (default: 50)

Example JQL queries:

• "project = PROJ AND status = Open"
• "assignee = currentUser() AND status != Done"
• "priority = High AND created >= -7d"

list_projects

List all accessible projects.

Parameters:

• maxResults (optional): Max results (default: 50)

Comments

add_comment

Add a comment to an issue.

Parameters:

• issueKey (required): Issue to comment on
• comment (required): Comment text

get_comments

Get all comments for an issue.

Parameters:

• issueKey (required): Issue key

Workflow Transitions

get_transitions

Get available status transitions for an issue.

Parameters:

• issueKey (required): Issue key

transition_issue

Change the status of an issue.

Parameters:

• issueKey (required): Issue to transition
• transitionId (required): Transition ID (from get_transitions)
• comment (optional): Comment to add with transition

API Reference

This server uses the Jira REST API v3.

Troubleshooting

"Error: JIRA_EMAIL and JIRA_API_TOKEN are required"

Make sure you've set the environment variables in your MCP configuration.

Authentication errors

• Verify your API token is correct
• Ensure your email matches your Atlassian account
• Check that your JIRA_BASE_URL doesn't have a trailing slash

Permission errors

The API token uses the permissions of the user who created it. Make sure your account has the necessary permissions for the actions you're trying to perform.

License

MIT

Author

Parth Dogra

Contributing

Feel free to open issues or submit pull requests for improvements!