Jira MCP server

This MCP Jira Integration server provides a bridge between Model Context Protocol (MCP) compatible LLMs and Jira, enabling AI assistants to act as project managers and personal assistants for Jira-based teams. It offers tools for issue management, sprint tracking, workload analysis, and automated report generation.

Installation

Prerequisites

Before installing, ensure you have:

• Python 3.8 or higher
• A Jira account with API token
• An MCP-compatible client (like Claude Desktop)

Setup Steps

1. Clone and install the package:

cd mcp-jira
pip install -e .

2. Configure your Jira credentials by creating an .env file with:

JIRA_URL=https://your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your_api_token
PROJECT_KEY=PROJ
DEFAULT_BOARD_ID=123

3. Launch the MCP server:

python -m mcp_jira.simple_mcp_server

Getting a Jira API Token

To obtain your Jira API token:

1. Visit the Atlassian Account Settings
2. Click "Create API token"
3. Name your token and copy it
4. Use your email as username and the token as password in your configuration

Usage

MCP Client Integration

Claude Desktop Integration

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-jira": {
      "command": "python",
      "args": ["-m", "mcp_jira.simple_mcp_server"],
      "cwd": "/path/to/mcp-jira"
    }
  }
}

Other MCP Clients

The server follows the standard MCP protocol and is compatible with any MCP-compliant client.

Core Features

Creating Issues

Simply ask the AI to create an issue with natural language:

"Create a high priority bug for the login system not working properly"

The system will automatically assign the proper issue type, priority, and formatting.

Sprint Management

Request sprint status information:

"What's our current sprint status?"

This will generate a comprehensive progress report with metrics and visual indicators.

Team Workload Analysis

Monitor team capacity and distribution:

"Show me the team workload for john.doe, jane.smith, mike.wilson"

The system will analyze capacity and provide workload distribution information.

Automated Standup Reports

Generate formatted daily standup reports:

"Generate today's standup report"

This creates a formatted report with completed, in-progress, and blocked items.

Configuration

Required Environment Variables

• JIRA_URL - Your Jira instance URL
• JIRA_USERNAME - Your Jira username/email
• JIRA_API_TOKEN - Your Jira API token
• PROJECT_KEY - Default project key for operations

Optional Settings

• DEFAULT_BOARD_ID - Default board ID for sprint operations
• DEBUG_MODE - Enable debug logging (default: false)
• LOG_LEVEL - Logging level (default: INFO)

Troubleshooting

Common Issues

1. "No active sprint found"

   • Verify that your board has an active sprint
   • Confirm that DEFAULT_BOARD_ID is set correctly

2. Authentication errors

   • Double-check your API token
   • Ensure your username is your complete email address

3. Permission errors

   • Verify your Jira user has appropriate project permissions
   • Confirm the project key exists and you have access

Debug Mode

For detailed logging, set DEBUG_MODE=true in your .env file.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "mcp-jira" '{"command":"python","args":["-m","mcp_jira.simple_mcp_server"],"cwd":"/path/to/mcp-jira"}'

See the official Claude Code MCP documentation for more details.

For 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 > Tools & Integrations and click "New MCP Server".

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

{
    "mcpServers": {
        "mcp-jira": {
            "command": "python",
            "args": [
                "-m",
                "mcp_jira.simple_mcp_server"
            ],
            "cwd": "/path/to/mcp-jira"
        }
    }
}

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 explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

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

2. Add this to your configuration file:

{
    "mcpServers": {
        "mcp-jira": {
            "command": "python",
            "args": [
                "-m",
                "mcp_jira.simple_mcp_server"
            ],
            "cwd": "/path/to/mcp-jira"
        }
    }
}

3. Restart Claude Desktop for the changes to take effect