Jira MCP server

Jira MCP is a Go-based connector that enables AI assistants like Claude to interact with Atlassian Jira. This tool provides a comprehensive interface for AI models to perform common Jira operations through natural language, covering everything from issue management to sprint planning.

Quick Start Guide

Prerequisites

Before you begin, you'll need:

1. Atlassian Account with access to a Jira instance
2. API Token from Atlassian
3. Cursor IDE with Claude integration

Getting Your Atlassian API Token

1. Go to Atlassian API Tokens
2. Click "Create API token"
3. Give it a name like "Jira MCP Connector"
4. Copy the token (you won't see it again!)

Installation Options

Using Docker (Recommended)

# Pull the latest image
docker pull ghcr.io/nguyenvanduocit/jira-mcp:latest

# Test it works (replace with your details)
docker run --rm \
  -e ATLASSIAN_HOST=your-company.atlassian.net \
  -e [email protected] \
  -e ATLASSIAN_TOKEN=your-api-token \
  ghcr.io/nguyenvanduocit/jira-mcp:latest \
  --http_port 3000

Using Pre-built Binary

1. Go to GitHub Releases
2. Download for your platform:
   • macOS: jira-mcp_darwin_amd64
   • Linux: jira-mcp_linux_amd64
   • Windows: jira-mcp_windows_amd64.exe
3. Make it executable (macOS/Linux):

   chmod +x jira-mcp_*
   sudo mv jira-mcp_* /usr/local/bin/jira-mcp
   

Using Go Install

go install github.com/nguyenvanduocit/jira-mcp@latest

Configuring Cursor IDE

1. Open Cursor
2. Go to Settings → Features → Model Context Protocol
3. Add a new MCP server with one of these configurations:

For Docker Users:

{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "ATLASSIAN_HOST=your-company.atlassian.net",
        "-e", "[email protected]", 
        "-e", "ATLASSIAN_TOKEN=your-api-token",
        "ghcr.io/nguyenvanduocit/jira-mcp:latest"
      ]
    }
  }
}

For Binary Users:

{
  "mcpServers": {
    "jira": {
      "command": "/usr/local/bin/jira-mcp",
      "env": {
        "ATLASSIAN_HOST": "your-company.atlassian.net",
        "ATLASSIAN_EMAIL": "[email protected]",
        "ATLASSIAN_TOKEN": "your-api-token"
      }
    }
  }
}

Testing Your Setup

1. Restart Cursor completely
2. Open a new chat with Claude
3. Try these test commands:

List my Jira projects

Show me issues assigned to me

What's in the current sprint?

If you see Jira data, your setup is complete!

Advanced Configuration

Using Environment Files

Create a .env file for easier management:

# .env file
ATLASSIAN_HOST=your-company.atlassian.net
[email protected]
ATLASSIAN_TOKEN=your-api-token

Then use it:

# With binary
jira-mcp -env .env

# With Docker
docker run --rm -i --env-file .env ghcr.io/nguyenvanduocit/jira-mcp:latest

HTTP Mode for Development

For development and testing, you can run in HTTP mode:

# Start HTTP server on port 3000
jira-mcp -env .env -http_port 3000

Then configure Cursor with:

{
  "mcpServers": {
    "jira": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Usage Examples

Once configured, you can ask Claude to help with Jira tasks using natural language:

Issue Management

• "Create a new bug ticket for the login issue"
• "Show me details for ticket PROJ-123"
• "Move ticket PROJ-456 to In Progress"
• "Add a comment to PROJ-789 saying the fix is ready"

Sprint Management

• "What's in our current sprint?"
• "Move these 3 tickets to the next sprint: PROJ-1, PROJ-2, PROJ-3"
• "Show me all tickets assigned to John in the current sprint"

Reporting & Analysis

• "Show me all bugs created this week"
• "List all tickets that are blocked"
• "What tickets are ready for testing?"

Troubleshooting

Common Issues

❌ "Connection failed" or "Authentication error"

• Double-check your ATLASSIAN_HOST (should be like company.atlassian.net)
• Verify your API token is correct
• Make sure your email matches your Atlassian account

❌ "No MCP servers found"

• Restart Cursor completely after adding the configuration
• Check the MCP configuration syntax in Cursor settings
• Verify the binary path is correct (for binary installations)

❌ "Permission denied" errors

• Make sure your Atlassian account has access to the Jira projects
• Check if your API token has the necessary permissions

Getting Help

1. Check the logs: Run with -http_port to see detailed error messages
2. Test your credentials: Try the Docker test command from the installation section
3. Verify Cursor config: The app will show you the exact configuration to use

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 "jira" '{"command":"docker","args":["run","--rm","-i","-e","ATLASSIAN_HOST=your-company.atlassian.net","-e","[email protected]","-e","ATLASSIAN_TOKEN=your-api-token","ghcr.io/nguyenvanduocit/jira-mcp:latest"]}'

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": {
        "jira": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-e",
                "ATLASSIAN_HOST=your-company.atlassian.net",
                "-e",
                "[email protected]",
                "-e",
                "ATLASSIAN_TOKEN=your-api-token",
                "ghcr.io/nguyenvanduocit/jira-mcp:latest"
            ]
        }
    }
}

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": {
        "jira": {
            "command": "docker",
            "args": [
                "run",
                "--rm",
                "-i",
                "-e",
                "ATLASSIAN_HOST=your-company.atlassian.net",
                "-e",
                "[email protected]",
                "-e",
                "ATLASSIAN_TOKEN=your-api-token",
                "ghcr.io/nguyenvanduocit/jira-mcp:latest"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect