Jira MCP server

This MCP server for Jira enables AI assistants to interact with your Jira instance, allowing them to act as project managers and personal assistants for teams. The server provides tools for creating issues, searching, generating reports, and analyzing team workloads.

Installation

Requirements

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

Setup Process

1. Clone and install the package:

cd mcp-jira-implementation/mcp-jira
pip install -e .

2. Configure Jira credentials in a .env file:

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

3. Run the MCP server:

python -m mcp_jira.simple_mcp_server

Getting a Jira API Token

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a name and copy the token
4. Use your email as username and the token as password

Usage

MCP Integration

With Claude Desktop

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"
    }
  }
}

With Other MCP Clients

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

Available Tools

Creating Issues

You can ask the AI to create a new issue:

"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

To check on your current sprint status:

"What's our current sprint status?"

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

Team Management

To analyze team workload:

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

The system will analyze capacity and provide workload distribution information.

Daily Standups

To generate standup reports:

"Generate today's standup report"

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

Configuration Options

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 for sprint operations
• DEBUG_MODE - Enable debug logging (default: false)
• LOG_LEVEL - Logging level (default: INFO)

Troubleshooting

Common Issues

1. "No active sprint found"

   • Make sure your board has an active sprint
   • Check that DEFAULT_BOARD_ID is set correctly

2. Authentication errors

   • Verify your API token is correct
   • Check that your username is your email address

3. Permission errors

   • Ensure your Jira user has appropriate project permissions
   • Check that the project key exists and you have access

Debug Mode

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

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.