Jira MCP server for AI agents

The Jira MCP server is a specialized tool that integrates Jira with AI assistants, providing sophisticated functionality for managing issues, sprints, and development workflows. It's designed based on real-world software development practices to handle practical tasks like retrieving linked pull requests and coordinating releases.

Installation Options

Using Docker

The easiest way to install and run the Jira MCP server is using Docker:

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

Using Binary

Alternatively, you can use the binary directly:

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

Configuration

Before using the Jira MCP server, you need to set up the following environment variables:

ATLASSIAN_HOST: Your Jira instance URL (e.g., https://your-company.atlassian.net)
ATLASSIAN_EMAIL: Your Atlassian email address
ATLASSIAN_TOKEN: Your Atlassian API token

Getting an API Token

To obtain an API token:

Go to https://id.atlassian.com/manage-profile/security/api-tokens
Create a new token
Copy the token and add it to your configuration

Using .env File (Local Installation)

If running locally, you can use a .env file:

ATLASSIAN_HOST=https://your-company.atlassian.net
[email protected]
ATLASSIAN_TOKEN=your-api-token

Usage

Quick Start Examples

Once installed, you can interact with the Jira MCP server through your AI assistant with natural language queries like:

"Show my issues assigned to me"
"What's in the current sprint for ABC?"
"Create a bug in ABC: Login fails on Safari"

Available Tools

Issue Management

jira_get_issue: Get detailed issue information
jira_create_issue: Create a new issue
jira_create_child_issue: Create a sub-task
jira_update_issue: Modify existing issues
jira_list_issue_types: List available issue types

Search

jira_search_issue: Search issues using JQL

Sprint Management

jira_list_sprints: List active and future sprints
jira_get_sprint: Get detailed sprint information
jira_get_active_sprint: Find the active sprint
jira_search_sprint_by_name: Search sprints by name

Status & Transitions

jira_list_statuses: List available issue statuses
jira_transition_issue: Move issues through workflow

Comments & Worklogs

jira_add_comment: Add comments to issues
jira_get_comments: Retrieve issue comments
jira_add_worklog: Track time spent on issues

History & Relationships

jira_get_issue_history: View complete change history
jira_get_related_issues: Find linked issues
jira_link_issues: Create relationships between issues

Version Management

jira_get_version: Get version details
jira_list_project_versions: List project versions

Development Information

jira_get_development_information: Retrieve linked branches, PRs, and commits

HTTP Mode (For Debugging)

For debugging purposes, you can run the server in HTTP mode:

jira-mcp -env .env -http_port 3000

Cursor configuration for HTTP mode:

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

This mode is helpful when troubleshooting or developing against the MCP server.

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