Skip to main content
Glama

JIRA MCP Server (Async)

Python 3.13+ MCP Compatible UV

An async Model Context Protocol (MCP) server and a jira CLI for JIRA Cloud integration via stdio transport.

MCP Tools

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

Tool

Description

Key Parameters

jira_search_issues

Search issues using JQL (paginated)

jql, max_results, start_at

jira_get_issue

Get issue details, comments, links; optionally subtasks and transitions

issue_key, include_subtasks, include_transitions

jira_create_issue

Create a new issue

project_key, summary, description, issue_type_name

jira_update_issue

Update fields on an existing issue, optionally add a comment

issue_key, summary, description, assignee, priority, labels, comment

jira_transition_issue

Move an issue through a workflow transition

issue_key, transition_id, comment

jira_link_issues

Link two issues with a typed relationship

issue_key, target_key, link_type

jira_add_remote_link

Attach a web link, such as a pull request, to an issue

issue_key, url, title

jira_get_create_meta

Get required fields and allowed values before creating an issue

project_key, issue_type

Related MCP server: Jira MCP Server

Features

  • Cloud only: JIRA Cloud v3 — Basic Auth, ADF, accountId assignees

  • Two entry points, one implementation: the MCP tools and the jira CLI call the same operations in mcp_jira/tools.py

  • 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, 238 unit tests, 98% line coverage

CLI

The jira console script has 12 commands: seven cover the eight MCP tools, plus five extras (comment, comments, project, field, me). JSON by default, so it pipes into jq; -o table and -o md are for reading.

jira me                                              # check credentials
jira search "assignee = currentUser()" -o table
jira issue OCPBUGS-1234 --transitions
jira meta OCPBUGS --issue-type Bug                  # required fields before creating
jira create OCPBUGS "etcd leader flaps" "Step 1..." Bug --priority Major
jira update OCPBUGS-1234 --comment "Reproduced on 4.18.3"
jira transition OCPBUGS-1234 31 --comment "Fixed in 4.18.4"
jira link OCPBUGS-1234 OCPBUGS-5678 --type Blocks  # 1234 blocks 5678
jira link OCPBUGS-1234 https://github.com/o/r/pull/1 --web --title "Fix PR"

Run jira --help for the full command reference. update refuses to run with no field flags, because an empty PUT reports success while changing nothing.

An agent-facing skill describing when and how to use the CLI is at skills/jira-cli/SKILL.md.

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

Variable

Description

Default

Required

JIRA_SERVER_URL

Your JIRA instance URL

—

Yes

JIRA_API_TOKEN

Your JIRA API token

—

Yes

JIRA_USER_EMAIL

Email for Basic Auth

—

Yes

MAX_CONCURRENT_REQUESTS

Max concurrent requests & rate limit (req/sec)

2

No

REQUEST_TIMEOUT

HTTP request timeout (seconds)

30

No

CONNECT_TIMEOUT

HTTP connection timeout (seconds)

10

No

LOG_LEVEL

Logging level

ERROR

No

LOG_TO_STDOUT

Enable stdout logging (breaks MCP stdio)

false

No

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

Add --scope project to install at project level (.claude/settings.json) instead of user level.

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

One package, plus a root shim so existing MCP client configs keep working:

  • mcp_jira/tools.py — the operations layer: the shared client and one async function per JIRA operation

  • mcp_jira/server.py — registers eight operations as MCP tools under their jira_* names, plus 2 prompt templates

  • mcp_jira/cli.py — the jira click CLI over the same operations

  • mcp_jira/client.py — AsyncJiraClient for JIRA Cloud v3, with JiraClientProtocol, retry, throttling, and the _transform_* response flatteners

  • jira_mcp_server.py — root shim re-exporting main and mcp from mcp_jira.server

Cloud is the only supported deployment: the v3 prefix and search endpoint are module constants, and JIRA_USER_EMAIL is required. See docs/adr/0002-cloud-only-and-shared-operations-layer.md for the rationale, and docs/adr/0001-cloud-detection-via-email.md for the decision this supersedes.

Available Tools

6 tools
jira_create_issueA

Creates a new issue in a specified Jira project. Requires project key, summary, description, and issue type. Optional fields include assignee, priority, labels, and custom fields.

On Cloud instances, pass an accountId string for assignee_name (not a username).

Args: project_key: Key of the project to create issue in (e.g., "PROJECT") summary: Issue summary description: Issue description issue_type_name: Type of the issue to create (e.g., "Bug", "Task") assignee_name: Assignee — accountId on Cloud, username on Server/DC (optional) priority_name: Name of the priority (optional) labels: List of labels to add to the issue (optional) custom_fields: Dictionary of custom fields to set (optional)

Returns: JSON object with the key of the new issue

Inputs: summary (required), description (required), project_key (required), issue_type_name (required), +4 more.

jira_get_create_metaA

Get metadata for creating issues — available issue types and their required/optional fields.

Call without issue_type to list available types. Call with issue_type to get field requirements.

Args: project_key: Project key (e.g., "OCPBUGS") issue_type: Issue type name (e.g., "Bug"). If omitted, lists available types.

Returns: Issue types list, or field details (name, required, allowed values) for one type

Inputs: project_key (required), issue_type.

jira_get_issueA

Get detailed information about a specific JIRA issue including comments and links. Optionally include subtasks and available workflow transitions.

Args: issue_key: The JIRA issue key (e.g., "PROJECT-123") include_subtasks: Also fetch subtasks (extra API call) include_transitions: Also fetch available workflow transitions (extra API call)

Returns: Issue details with comments, links, and optionally subtasks/transitions

Inputs: issue_key (required), include_subtasks, include_transitions.

jira_search_issuesA

Search for JIRA issues using JQL (JIRA Query Language).

Returns a paginated result with total count. Use start_at to page through large result sets.

Args: jql: JQL query string (e.g., "project = PROJECT AND status = 'In Progress'") max_results: Maximum number of results to return (default: 50) start_at: Index of the first result (default: 0, for pagination)

Returns: Dict with issues array, total count, start_at, and max_results

Inputs: jql (required), start_at, max_results.

jira_transition_issueA

Transition a JIRA issue to a new workflow state. Use jira_get_issue with include_transitions=True to see available transitions and their IDs.

Args: issue_key: The JIRA issue key (e.g., "PROJECT-123") transition_id: ID of the transition to execute (from jira_get_issue transitions) comment: Optional comment to add with the transition

Returns: Confirmation with issue key

Inputs: issue_key (required), transition_id (required), comment.

jira_update_issueA

Update fields on an existing JIRA issue. All field parameters are optional — only provided fields are updated. Optionally add a comment in the same call.

On Cloud instances, pass an accountId string for assignee (not a username).

Args: issue_key: The JIRA issue key (e.g., "PROJECT-123") summary: New summary (optional) description: New description (optional) assignee: New assignee — accountId on Cloud, username on Server/DC (optional) priority: New priority name (optional) labels: New labels list — replaces existing labels (optional) comment: Comment to add after update (optional) custom_fields: Dictionary of custom fields to update (optional)

Returns: Confirmation with issue key

Inputs: issue_key (required), labels, comment, summary, +4 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a distinct operation: search, get, create, update, transition, and metadata. No overlap exists; search returns lists while get returns single issue details, and transition handles workflow state changes.

    Naming Consistency5/5

    All tool names follow the jira_verb_noun pattern consistently (jira_search_issues, jira_get_issue, etc.). The one compound verb 'get_create_meta' still follows the verb_noun convention.

    Tool Count5/5

    Six tools cover the core Jira issue lifecycle without being excessive. The count is well-scoped for a focused issue management server.

    Completeness4/5

    Core CRUD and workflow transitions are covered: search, get, create, update, transition, and create metadata. Minor gaps include no delete issue or dedicated comment tool, but comments can be added via update/transition.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      B
      maintenance
      MCP server that connects AI assistants to your Jira site, supporting PAT or SSO authentication for search, read, create, update, and delete operations on issues.
      17
      110 npm
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides AI assistants with access to Jira Cloud for issue management, search, and workflow operations.
      -