JIRA MCP Server (Async)

An async Model Context Protocol (MCP) server for JIRA integration via stdio transport. Supports both Atlassian Cloud and Server/DC instances.

MCP Tools

6 tools covering the full issue lifecycle, plus 2 prompt templates:

Related MCP server: Jira MCP Server

Features

• Cloud + Server/DC: Auto-detects deployment type via JIRA_USER_EMAIL env var

• Token optimization: API responses transformed to 40-60% fewer tokens

• ADF support: Reads and writes Atlassian Document Format (Cloud v3)

• Connection pooling: aiohttp with configurable pool size

• Rate limiting: Built-in throttling with exponential backoff on 429s

• Testable: Injectable client via _set_client(), session injection for HTTP-level tests, 113 unit tests

Setup

Prerequisites

• Python 3.13+

• uv package manager

• JIRA API token

Installation

git clone https://github.com/judexzhu/mcp-jira.git
cd mcp-jira
uv sync
cp config.env.example .env
# Edit .env with your JIRA credentials

Environment Variables

Claude Desktop

Add to your Claude Desktop MCP config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-jira", "python", "jira_mcp_server.py"],
      "env": {
        "JIRA_SERVER_URL": "https://your-company.atlassian.net",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_USER_EMAIL": "you@company.com"
      }
    }
  }
}

Claude Code

Add to your Claude Code MCP settings (.claude/settings.json or global ~/.claude/settings.json):

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-jira", "python", "jira_mcp_server.py"],
      "env": {
        "JIRA_SERVER_URL": "https://your-company.atlassian.net",
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_USER_EMAIL": "you@company.com"
      }
    }
  }
}

Or add via CLI:

claude mcp add jira \
  -e JIRA_SERVER_URL=https://your-company.atlassian.net \
  -e JIRA_API_TOKEN=your_api_token \
  -e JIRA_USER_EMAIL=you@company.com \
  -- uv run --directory /path/to/mcp-jira python jira_mcp_server.py

Alternatively, skip the -e flags and put credentials in a .env file inside the mcp-jira directory — load_dotenv() picks them up automatically.

Testing

# Unit tests (no credentials needed)
uv sync --group dev
uv run pytest tests/ -v

Architecture

Two-file core:

• jira_mcp_server.py — 6 MCP tool functions + 2 prompt templates, each a thin wrapper delegating to the client

• jira_client.py — AsyncJiraClient with JiraClientProtocol seam, _CloudFormat/_ServerFormat adapters, auth, connection pooling, rate limiting, retry, and response transformation

Cloud vs Server/DC is detected by the presence of JIRA_USER_EMAIL. See docs/adr/0001-cloud-detection-via-email.md for the rationale.