Jira MCP server

The JIRA MCP Server provides access to JIRA data with relationship tracking, optimized data payloads, and data cleaning for AI context windows. It supports both Jira Cloud and Jira Server (Data Center) instances, making it versatile for different deployment types.

Features

• Search JIRA issues using JQL (maximum 50 results per request)
• Retrieve epic children with comment history and optimized payloads (maximum 100 issues per request)
• Get detailed issue information including comments and related issues
• Create, update, and manage JIRA issues
• Add comments to issues
• Extract issue mentions from Atlassian Document Format
• Track issue relationships (mentions, links, parent/child, epics)
• Clean and transform rich JIRA content for AI context efficiency
• Support for file attachments with secure multipart upload handling
• Support for both Jira Cloud and Jira Server (Data Center) APIs

Prerequisites

• Bun (v1.0.0 or higher)
• JIRA account with API access

Installation & Setup

1. Clone the repository:

git clone [repository-url]
cd jira-mcp

2. Install dependencies and build:

bun install
bun run build

3. Configure the MCP server:

Edit the appropriate configuration file:

macOS:

• Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

• Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
• Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

• Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Add the following configuration under the mcpServers object:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_BASE_URL": "your_jira_instance_url",
        "JIRA_USER_EMAIL": "your_email",
        "JIRA_TYPE": "cloud"
      }
    }
  }
}

4. Restart the MCP server

Within Cline's MCP settings, restart the MCP server. Restart Claude Desktop to load the new MCP server.

Environment Variables

JIRA_API_TOKEN=your_api_token
JIRA_BASE_URL=your_jira_instance_url  # e.g., https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email
JIRA_TYPE=cloud   # or 'server' for Jira Server/Data Center (optional, defaults to 'cloud')

Available MCP Tools

search_issues

Search JIRA issues using JQL. Returns up to 50 results per request.

Input Schema:

{
  searchString: string; // JQL search string
}

get_epic_children

Get all child issues in an epic including their comments and relationship data. Limited to 100 issues per request.

Input Schema:

{
  epicKey: string; // The key of the epic issue
}

get_issue

Get detailed information about a specific JIRA issue including comments and all relationships.

Input Schema:

{
  issueId: string; // The ID or key of the JIRA issue
}

create_issue

Create a new JIRA issue with specified fields.

Input Schema:

{
  projectKey: string, // The project key where the issue will be created
  issueType: string, // The type of issue (e.g., "Bug", "Story", "Task")
  summary: string, // The issue summary/title
  description?: string, // Optional issue description
  fields?: { // Optional additional fields
    [key: string]: any
  }
}

update_issue

Update fields of an existing JIRA issue.

Input Schema:

{
  issueKey: string, // The key of the issue to update
  fields: { // Fields to update
    [key: string]: any
  }
}

add_attachment

Add a file attachment to a JIRA issue.

Input Schema:

{
  issueKey: string, // The key of the issue
  fileContent: string, // Base64 encoded file content
  filename: string // Name of the file to be attached
}

add_comment

Add a comment to a JIRA issue. Accepts plain text and converts it to the required Atlassian Document Format internally.

Input Schema:

{
  issueIdOrKey: string, // The ID or key of the issue to add the comment to
  body: string // The content of the comment (plain text)
}

Error Handling

The server implements a comprehensive error handling strategy:

• Network error detection and appropriate messaging
• HTTP status code handling (especially 404 for issues)
• Detailed error messages with status codes
• Error details logging to console
• Input validation for all parameters
• Safe error propagation through MCP protocol
• Specialized handling for common JIRA API errors
• Base64 validation for attachments
• Multipart request failure handling
• Rate limit detection
• Attachment parameter validation

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.