jira-mini-mcp
A Jira Cloud MCP server for coding agents that provides six read tools and three write tools to search, inspect, and update Jira issues with compact, predictable output.
Search issues with JQL, including pagination and selecting only the fields you need.
Fetch one issue's core state, fields, links, subtasks, custom fields, watchers/voters, and currently available transitions.
List an issue's comments with ordering, pagination, and optional since filter.
List attachment metadata and download attachment content to a temporary local path.
View an issue's changelog/field-change history with ordering and pagination.
Add comments in Markdown, automatically converted to Jira rich text.
Transition an issue through its workflow by transition or status name, optionally posting a comment in the same call.
Update issue fields: summary, description, assignee, labels, components, priority, duedate, parent, and custom fields; labels/components are replaced wholesale.
Run in read-only mode to expose only the six read tools and withhold all write tools.
Authenticate via Jira API token or OAuth 2.0 with automatic refresh.
Provides read-only integration with Jira Cloud, allowing agents to search issues with JQL, retrieve issue details, comments, attachments, and changelogs.
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., "@jira-mini-mcp find open bugs assigned to me in the current sprint"
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-mini-mcp
A Jira Cloud MCP server for coding agents: 6 read tools, 9 with writes enabled.
One job. One tool. Done right.
General-purpose Atlassian MCP servers expose dozens to hundreds of tools. Every one costs context before the agent does any useful work, and every near-duplicate makes the agent's choice less certain. This server gives a coding agent the Jira context it needs for a ticket, the three ways to answer back, and nothing else.
6-9 tools, not 98 - every one earns its place in context, and the descriptions are tested so an agent picks the right one; see why so few and how it's compared with the alternatives.
A write surface of exactly three tools - comment, transition, update. Set
READ_ONLY_MODE=trueand they never register, not even as a disabled entry the agent can see.Compact, predictable output - stable JSON schemas, Markdown for rich text, no
nullspam, noselfURLs, emails, or avatars; see what the tools return.Roughly 40% less output on the wire - each result is sent once, as JSON in
content, rather than again asstructuredContent; setSTRUCTURED_OUTPUT=trueif your host needs the typed copy. See Cheaper output.Nothing is silently cut short - exact totals on comments and changelog, cursor paging on search, and
limit=0to fetch the rest. A failed request is an error, never an empty list.Errors an agent can act on - a wrong transition name lists every valid transition and where it leads, so there is no separate discovery tool. Errors never contain your Jira URL, credentials, or raw response bodies.
API token or OAuth - one minute with an API token, or a browser login through your own OAuth 2.0 app with automatic refresh; see Configure.
On PyPI -
uvx jira-mini-mcporpip install jira-mini-mcp, no repo clone or git URL required.
Tool | Access | Purpose |
| 🟢 read | Find issues with JQL |
| 🟢 read | One issue's core state and fields |
| 🟢 read | Recent or historical discussion, paginated |
| 🟢 read | Attachment metadata |
| 🟢 read | Fetch one attachment |
| 🟢 read | Field-change history, paginated |
| 🔴 write | Post one Markdown comment |
| 🔴 write | Move an issue through its workflow |
| 🔴 write | Set issue fields |
SetREAD_ONLY_MODE=true and only the six 🟢 read tools register - the
three 🔴 write tools are withheld entirely, see Configure.
More detail lives in docs/: configuration,
OAuth setup, and what the tools return, with
examples.
Install
uvx jira-mini-mcpor
pip install jira-mini-mcpPin a version when you want a fixed surface: uvx jira-mini-mcp==1.1.0.
Running an unreleased commit straight from GitHub also works:
uvx --from git+https://github.com/proprock/jira-mini-mcp jira-mini-mcpRequires Python 3.12+ and uv (or pip).
Related MCP server: Simple Jira MCP
Configure
With an API token, three values:
Variable | Meaning |
| Your site, e.g. |
| The email your API token belongs to |
|
Add READ_ONLY_MODE=true to withhold the write tools. Every setting, including
STRUCTURED_OUTPUT, is in configuration.md.
Prefer OAuth to a stored token? Set JIRA_AUTH_METHOD=oauth, register a
free OAuth 2.0 (3LO) app, and run jira-mini-mcp login once to authorize in
your browser. The server then refreshes its token by itself. Step by step:
oauth.md.
Configuration is validated at startup, and an error names the missing setting without printing its value or your Jira URL. Keep the token in the host's own configuration and never commit it. The server acts with your account's permissions: an account that cannot transition an issue still cannot, whatever this server exposes.
claude mcp add --env JIRA_BASE_URL=https://example.atlassian.net --env JIRA_EMAIL=you@example.com --env JIRA_API_TOKEN=your-token --transport stdio jira-mini -- uvx jira-mini-mcpPut at least one other option between the last --env and the server name, as
above - the CLI otherwise reads the name as another KEY=value pair.
In claude_desktop_config.json:
{
"mcpServers": {
"jira-mini": {
"command": "uvx",
"args": ["jira-mini-mcp"],
"env": {
"JIRA_BASE_URL": "https://example.atlassian.net",
"JIRA_EMAIL": "you@example.com",
"JIRA_API_TOKEN": "your-token"
}
}
}
}codex mcp add jira-mini --env JIRA_BASE_URL=https://example.atlassian.net --env JIRA_EMAIL=you@example.com --env JIRA_API_TOKEN=your-token -- uvx jira-mini-mcpCommand uvx, argument jira-mini-mcp, and the three environment variables.
Add READ_ONLY_MODE=true to withhold the write tools. OAuth host examples are in
oauth.md.
Writing to Jira
Three tools, chosen so an agent can close the loop on a ticket it worked:
add_comment(issue_key, body)
transition_issue(issue_key, to, comment=None)
update_issue(issue_key, fields)Issue creation, links, attachment upload, worklogs, and deletion are out of scope. Creation needs per-project, per-type required-field discovery and is a feature in its own right; a link, or a request for one, fits in a comment.
Three things are worth knowing before an agent writes:
transition_issuetakes a name, not an id. A transition name or the name of the status to reach, matched ignoring case. They differ in real workflows - a transition calledIn Progresscan produce a status calledIn Development, and two differently named transitions can reach one status - so prefer the transition name. When nothing matches, the error lists every available transition and where it leads. To see the options first, askget_issue(fields=["transitions"]). That is why there is no separateget_transitionstool.update_issuereplaceslabelsandcomponentswholesale. There is no add or remove verb, so read the issue first if you mean to add one value. It takes the same valuesget_issuereturns:assigneeas an account id, an email, a display name, or the literal"me",descriptionas Markdown,customfield_*as raw Jira JSON. It refusesstatusandcomment, naming the tool that does each.Markdown is converted, not guessed at. Headings, lists, fenced code, inline marks, and links become Jira rich text; anything outside that set stays literal rather than being reinterpreted.
Each write tool is annotated readOnlyHint=false with honest destructiveHint
and idempotentHint values, which is what READ_ONLY_MODE filters on.
Why so few tools
A tool definition is a name, a description, an input schema, and often an output contract. Depending on the client, all of it enters the model's context before any work happens. A large toolset therefore spends context on capabilities the current task will never use, and raises the chance of picking the wrong tool, confusing similar ones, or passing bad parameters.
Six to nine compact schemas stay affordable for a whole session, leaving the context budget for source code, issue descriptions, stack traces, and reasoning. The design follows Anthropic's guidance for agent systems: keep toolsets small, role-scoped, and clearly differentiated.
This is a claim, so the repository tests it. The offline half runs with the suite
and checks that every tool is described substantially, that no two descriptions
are near-duplicates, and that every parameter whose behavior cannot be guessed
from its name is explained in prose. The other half puts the real tool
definitions in front of a real model and scores which one it picks - see
evals/README.md.
The same principle shapes the responses. get_issue does not dump hundreds of
comments, the full changelog, attachment contents, or every custom field; large
resources are fetched only when asked for.
Compared with the alternatives
jira-mini-mcp | |||
Scope | Jira only | Jira, Confluence, JSM, Bitbucket, Compass, Loom, and more | Jira and Confluence |
Deployments | Cloud | Cloud | Cloud, Server/Data Center |
Hosting | Local, stdio | Remote, Atlassian-hosted | Local (stdio, Docker) or HTTP |
Auth | API token or OAuth 2.0 (own app) | OAuth 2.1 or API token | API token, PAT, or OAuth 2.0 (own app) |
Tools | 6-9, always visible | A small default set with on-demand discovery | 98 |
Writes | 3 tools | Yes, admin-gated by category | Yes |
License | MIT | Apache 2.0 | MIT |
The official server is the better choice when you need breadth across Atlassian products, OAuth without registering an app of your own, Jira Service Management, or organization-level controls such as permission groups, IP allowlisting, and audit logs. It is Atlassian's own product, it tracks their APIs, and nothing here competes with that.
mcp-atlassian is the better choice when you need Confluence alongside Jira,
Server/Data Center, or simply broader Jira coverage than six to nine tools.
This server is the better choice for one narrow case: a coding agent working a Jira ticket, where the context every tool definition costs is worth more than the coverage it buys.
Contributing and security
Setup, checks, the test and eval commands, the branch and commit conventions, and the release model are in CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md. Changes that affect someone running the server are recorded in CHANGELOG.md.
License
MIT. Not an official Atlassian product.
Available Tools
9 toolsadd_commentA
Add one comment to an issue. body is Markdown -- headings, lists, fenced code blocks, bold/italic, inline code, links -- converted to Jira's rich text; anything outside that set stays literal. Returns the created comment in the same shape get_comments returns. This server cannot edit or delete a comment afterwards.
Inputs: body (required), issue_key (required).
download_attachmentARead-onlyIdempotent
Download one attachment by id into a process-scoped temporary cache and return its local_path. The cache is removed when the server shuts down.
Inputs: attachment_id (required).
get_attachmentsARead-onlyIdempotent
List an issue's attachment metadata (id, filename, mime_type, size, author, created) without downloading content. Use download_attachment to fetch a file's bytes.
Inputs: issue_key (required).
get_changelogARead-onlyIdempotent
List an issue's field-change history. order='desc' (default) returns newest first; 'asc' returns oldest first. start_at/limit paginate the logical, sorted collection (ties broken by entry id); limit=0 returns every remaining entry from start_at with no cap. Each entry lists human-readable field changes.
Inputs: issue_key (required), limit, order, start_at.
get_commentsARead-onlyIdempotent
List an issue's comments. order='desc' (default) returns newest first; 'asc' returns oldest first. start_at/limit paginate the logical, filtered, sorted collection (ties broken by comment id); limit=0 returns every remaining comment from start_at with no 100-comment cap. since (ISO-8601 with an explicit offset) keeps only comments created at or after that instant, and total reflects the filtered collection.
Inputs: issue_key (required), limit, order, since, +1 more.
get_issueARead-onlyIdempotent
Fetch one issue by key. fields replaces the default fields entirely -- default: summary, description, issuetype, status, priority, assignee, reporter, labels, components, created, updated, resolutiondate, issuelinks, project, parent, subtasks. fields=[] returns the key with no fields. Requesting 'watches' or 'votes' resolves the real watcher/voter list (watch_count/is_watching/watchers, vote_count/has_voted/voters) via one extra request per field, instead of Jira's own link-only stub. When fields names any customfield_*, the result adds field_names mapping each returned customfield id to its display name. 'transitions' lists the moves available now (id, name, resulting status), the same names transition_issue accepts. Does not include comments, attachments, or changelog history; use the dedicated tools for those.
Inputs: issue_key (required), fields.
search_issuesARead-onlyIdempotent
Search Jira Cloud issues with JQL. Returns items and an opaque next_page_token (null on the last page); pass it back as page_token for the next page. limit is 1..100 (default 20); 0 is invalid. fields replaces the default fields entirely -- default: summary, status, issuetype, priority, assignee, updated, project. fields=[] returns only the issue key.
Inputs: jql (required), limit, fields, page_token.
transition_issueADestructive
Move an issue through its workflow. to is a transition name or the name of the status to reach, matched ignoring case and surrounding space. A transition's name often differs from the status it leads to (a transition called 'In Progress' can produce status 'In Development'), and two transitions can reach one status, so prefer the transition name; if nothing matches, the error lists every available transition and its resulting status. comment is Markdown and is posted in the same call as the move. Changes issue state.
Inputs: to (required), issue_key (required), comment.
update_issueADestructiveIdempotent
Set issue fields, taking the same values get_issue returns: summary as text, description as Markdown, assignee as an account id, an email, a display name, or the literal "me" (an ambiguous name is an error listing the candidates), labels as a list, components and priority by name, duedate as YYYY-MM-DD, parent as an issue key, and any customfield_* or unknown field as raw Jira JSON. null clears assignee, description, priority, parent, or duedate. labels and components REPLACE the whole list, so read the issue first if you mean to add one. Cannot change status (use transition_issue) or add a comment (use add_comment).
Inputs: fields (required), issue_key (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct resource or action: search vs. fetch, comments, attachment metadata vs. download, changelog, add comment, transition, update. The get_issue description explicitly excludes comments, attachments, and changelog, and get_attachments vs. download_attachment are clearly separated by metadata vs. content.
All tool names follow a consistent verb_noun pattern with lowercase and underscores: search_issues, get_issue, get_comments, get_attachments, download_attachment, get_changelog, add_comment, transition_issue, update_issue. No mixing of conventions.
9 tools is well within the ideal 3-15 range, and each tool covers a distinct aspect of Jira issue interaction without redundancy or bloat.
The set is missing create_issue and delete_issue, which are core lifecycle operations for an issue tracker. While it covers reading, updating, transitioning, and adding comments, the absence of create/delete is a significant gap that will cause agent failures when those actions are needed.
Maintenance
Related MCP Connectors
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
MCP-first toolbox for agents: KV storage, auth, queue, and utility tools. Free in early access.
Pay-per-use tool marketplace for AI agents. Search, price-check, and call APIs via MCP.
Patterns for designing and reviewing AI skills, agents, and multi-agent workflows. Find guidance on context economy, delegation, verification, and tool design; inspect claims, worked examples, maturity labels, and source references. Five read-only tools let agents discover relevant patterns, compare concise cards, read specific sections, and explore relationships. Hosted Streamable HTTP at https://agentic-atlas.dev/mcp/ — no installation, account, or API key required. Browse the atlas at https://agentic-atlas.dev/.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides tools for AI assistants to interact with JIRA APIs, enabling them to read, create, update, and manage JIRA issues through standardized MCP tools.63MIT
- AlicenseAqualityBmaintenanceProvides Jira Cloud integration for AI agents, enabling them to search issues with JQL, retrieve detailed issue information, and create new tickets. It supports multiple Jira configurations and provides tools for managing attachments and comments through natural language.12MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language interaction with JIRA through MCP, providing 35 tools for issues, comments, transitions, projects, boards, sprints, epics, links, worklogs, versions, attachments, users, and fields.MIT
- FlicenseNot gradedqualityDmaintenanceEnables natural language interaction with Jira Cloud tickets, including listing, searching, creating, and updating issues through a set of MCP tools.-