vidhikachakravarti/jira-mcp

Jira MCP Server

A Model Context Protocol (MCP) server that provides integration with Jira. This allows AI assistants like Claude to interact with Jira to search, create, update, and manage issues.

Features

• Search Issues: Search for issues using JQL (Jira Query Language)
• Get Issue Details: Retrieve detailed information about specific issues
• Create Issues: Create new Jira issues with customizable fields
• Update Issues: Modify existing issue details
• Transition Issues: Move issues through workflow states
• Add Comments: Add comments to issues
• List Projects: Get all accessible projects

Prerequisites

• Node.js 18 or higher
• A Jira account with API access
• Jira API token (instructions below)

Getting Your Jira API Token

1. Log in to your Jira account
2. Go to https://id.atlassian.com/manage-profile/security/api-tokens
3. Click "Create API token"
4. Give it a label and click "Create"
5. Copy the token (you won't be able to see it again)

Installation

1. Clone this repository or create the project:

npm install

2. Build the TypeScript code:

npm run build

3. Create a .env file with your Jira credentials:

cp .env.example .env

Then edit .env with your actual values:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token

Configuration

For Claude Desktop

Add this to your Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

For Other MCP Clients

Run the server with:

JIRA_BASE_URL='https://your-domain.atlassian.net'
JIRA_EMAIL='your-email@example.com'
JIRA_API_TOKEN='your-api-token-here'
node build/index.js

Available Tools

search_issues

Search for Jira issues using JQL.

Parameters:

• jql (required): JQL query string (e.g., "project = PROJ AND status = Open")
• maxResults (optional): Maximum number of results (default: 50)

Example:

Search for all open bugs in project PROJ:
jql: "project = PROJ AND issuetype = Bug AND status = Open"

get_issue

Get detailed information about a specific issue.

Parameters:

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

create_issue

Create a new Jira issue.

Parameters:

• projectKey (required): The project key (e.g., "PROJ")
• summary (required): Issue title/summary
• issueType (required): Issue type (e.g., "Task", "Bug", "Story")
• description (optional): Issue description
• priority (optional): Priority (e.g., "High", "Medium", "Low")
• assignee (optional): Assignee user ID

update_issue

Update an existing issue.

Parameters:

• issueKey (required): The issue key
• summary (optional): New summary
• description (optional): New description
• priority (optional): New priority
• assignee (optional): New assignee user ID

get_transitions

Get available workflow transitions for an issue.

Parameters:

• issueKey (required): The issue key

transition_issue

Transition an issue to a new status.

Parameters:

• issueKey (required): The issue key
• transitionId (required): The transition ID (get from get_transitions)

add_comment

Add a comment to an issue.

Parameters:

• issueKey (required): The issue key
• comment (required): The comment text

get_projects

Get all accessible Jira projects. No parameters required.

JQL Examples

Here are some useful JQL queries:

• All open issues: status = Open
• My assigned issues: assignee = currentUser()
• Recent updates: updated >= -7d
• High priority bugs: priority = High AND issuetype = Bug
• Issues in sprint: sprint in openSprints()

Development

Watch mode for development:

npm run dev

Troubleshooting

Authentication Errors

• Verify your API token is correct
• Ensure your email matches your Jira account
• Check that your base URL is correct (no trailing slash)

Permission Errors

• Ensure your Jira account has appropriate permissions
• Some operations require specific project roles

Connection Issues

• Verify your Jira instance is accessible
• Check firewall/proxy settings if applicable

License

MIT