mcp-jira
This MCP server provides JIRA Cloud issue-management capabilities through MCP tools and a shared jira CLI.
Search issues using JQL with pagination.
Get issue details including comments and links, optionally subtasks and workflow transitions.
Create issues with summary, description, issue type, assignee, priority, labels, and custom fields.
Update issue fields and optionally add a comment.
Transition issues through workflow states with an optional comment.
Retrieve create metadata: available issue types and required/allowed fields per issue type.
Provides tools for searching, creating, updating, and managing JIRA issues, including comments, links, epics, subtasks, and workflow transitions, via the JIRA API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-jira search for open bugs in project PROJ using JQL"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
JIRA MCP Server (Async)
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 |
| Search issues using JQL (paginated) |
|
| Get issue details, comments, links; optionally subtasks and transitions |
|
| Create a new issue |
|
| Update fields on an existing issue, optionally add a comment |
|
| Move an issue through a workflow transition |
|
| Link two issues with a typed relationship |
|
| Attach a web link, such as a pull request, to an issue |
|
| Get required fields and allowed values before creating an issue |
|
Related MCP server: Jira MCP Server
Features
Cloud only: JIRA Cloud v3 — Basic Auth, ADF,
accountIdassigneesTwo entry points, one implementation: the MCP tools and the
jiraCLI call the same operations inmcp_jira/tools.pyToken optimization: API responses transformed to 40-60% fewer tokens
ADF support: Reads and writes Atlassian Document Format (Cloud v3)
Connection pooling:
aiohttpwith configurable pool sizeRate 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 credentialsEnvironment Variables
Variable | Description | Default | Required |
| Your JIRA instance URL | — | Yes |
| Your JIRA API token | — | Yes |
| Email for Basic Auth | — | Yes |
| Max concurrent requests & rate limit (req/sec) |
| No |
| HTTP request timeout (seconds) |
| No |
| HTTP connection timeout (seconds) |
| No |
| Logging level |
| No |
| Enable stdout logging (breaks MCP stdio) |
| 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.pyAdd --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/ -vArchitecture
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 operationmcp_jira/server.py— registers eight operations as MCP tools under theirjira_*names, plus 2 prompt templatesmcp_jira/cli.py— thejiraclick CLI over the same operationsmcp_jira/client.py—AsyncJiraClientfor JIRA Cloud v3, withJiraClientProtocol, retry, throttling, and the_transform_*response flattenersjira_mcp_server.py— root shim re-exportingmainandmcpfrommcp_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 toolsjira_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
Scored across 6 tools
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.
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.
Six tools cover the core Jira issue lifecycle without being excessive. The count is well-scoped for a focused issue management server.
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
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
MCP server for Sentry - error monitoring, issue tracking, and debugging for AI assistants
Remote MCP server to run your Atako AI agents: chat, projects, files, integrations and channels.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA production-ready MCP server for JIRA integration that enables AI assistants to query JIRA issues and perform searches using natural language through JQL.1-
- AlicenseNot gradedqualityDmaintenanceA comprehensive MCP server for Atlassian Jira that enables AI assistants to manage issues, sprints, comments, and worklogs through natural language.MIT
- FlicenseBqualityBmaintenanceMCP server that connects AI assistants to your Jira site, supporting PAT or SSO authentication for search, read, create, update, and delete operations on issues.17110 npm-
- FlicenseNot gradedqualityDmaintenanceMCP server that provides AI assistants with access to Jira Cloud for issue management, search, and workflow operations.-