jira-mini-mcp

A nine-tool Jira Cloud MCP server for coding agents.

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.

Six read, three write. READ_ONLY_MODE=true registers the six alone.

• Install
• Configure
• What the tools return
• Writing to Jira
• Why so few tools
• Compared with the alternatives
• Development
• Release model

Install

No installation step: run it straight from GitHub.

uvx --from git+https://github.com/proprock/jira-mini-mcp jira-mini-mcp

Pin a release when you want a fixed surface:

uvx --from git+https://github.com/proprock/jira-mini-mcp@v0.1.0 jira-mini-mcp

Requires Python 3.12+ and uv. Starting with the next tagged release, the release workflow also publishes to PyPI, after which uvx jira-mini-mcp will be enough.

Configure

Three required values, and one optional switch:

Authentication is Jira Cloud Basic auth with the email and token. Jira Server/Data Center, PAT/Bearer, and OAuth are not supported. Configuration is validated at startup, and an error names the missing setting without printing its value or your Jira URL. An unrecognized READ_ONLY_MODE value stops startup rather than quietly re-enabling the write tools.

Keep the token in the host's own configuration and never commit it. The token carries its 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 --from git+https://github.com/proprock/jira-mini-mcp jira-mini-mcp

{
  "mcpServers": {
    "jira-mini": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/proprock/jira-mini-mcp",
        "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 --from git+https://github.com/proprock/jira-mini-mcp jira-mini-mcp

What the tools return

Structured JSON with stable output schemas, and no second human-readable rendering of the same result. Jira's rich text becomes Markdown inside the corresponding string field. Timestamps normalize to UTC ISO-8601 with a Z. Users are account_id and display_name only — no email, avatar, or self URL. Known resources use compact shapes:

issuetype  = {id, name, hierarchy_level}
status     = {id, name, category}
priority   = {id, name}
project    = {id, key, name}
components = [{id, name}, ...]
issue      = {key, summary?, status?, issuetype?}
issuelink  = {relationship, issue}

Absent and unrequested values are omitted rather than returned as null. Explicitly requested unknown or customfield_* values are preserved as Jira JSON. If Jira returns a malformed known resource but the rest is usable, the call fails with the exact JSON paths and a sanitized partial result rather than pretending the data was fine.

Fields

search_issues defaults to these seven fields:

summary, status, issuetype, priority, assignee, updated, project

get_issue defaults to these sixteen fields:

summary, description, issuetype, status, priority, assignee, reporter,
labels, components, created, updated, resolutiondate, issuelinks,
project, parent, subtasks

An explicit fields list replaces the default completely; the server adds no hidden fields. fields=[] returns issue keys only.

Pagination

Large collections never pretend to be complete. get_comments and get_changelog return start_at, an exact total, and items — more exist when start_at + len(items) < total, and that sum is the next offset. Both default to order="desc" (offset zero is the newest item) and to 20 items; limit=0 returns everything remaining from start_at, with no 100-item cap. get_comments also takes since, applied before ordering and slicing, so "what happened since the last release" does not mean loading a multi-year discussion.

search_issues is the exception. The current Jira Cloud enhanced search API is cursor-based with no exact total; its count endpoint is approximate and the old offset endpoint is being removed. So search returns items and next_page_token only — pass the token back as page_token, and a null token means the last page. limit is 1..100; zero is rejected with guidance rather than silently treated as a default.

Attachments

get_attachments returns metadata only. Only when a file matters does the agent call download_attachment, which writes into an automatically managed process-scoped temporary cache and returns a local path. No download directory to configure, and the cache is removed at shutdown.

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_issue takes 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 called In Progress can produce a status called In 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. That listing is the discovery mechanism, which is why there is no separate get_transitions tool.
• update_issue replaces labels and components wholesale. There is no add or remove verb, so read the issue first if you mean to add one value. It takes the same values get_issue returns: assignee as an account id or the literal "me", description as Markdown, customfield_* as raw Jira JSON. It refuses status and comment, 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.

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

The official server is the better choice when you need breadth across Atlassian products, OAuth rather than a stored token, 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 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.

Development

uv sync
uv run ruff format --check .
uv run ruff check .
uv run ty check
uv run pytest
uv run pytest --cov=jira_mini_mcp --cov-branch --cov-report=term-missing

uv run ruff format . applies formatting. The last command reports statement and branch coverage with missing lines; it is reviewed before closing each phase, and the project deliberately has no fail-under percentage until a meaningful baseline exists.

The default suite is fully offline. HTTP mocks trace to observations against a real Jira Cloud site, but raw responses are never committed: each fixture keeps the observed structure while every tenant, account, issue, cursor, timestamp, and content value is synthetic, and records its own provenance. Write endpoints are exercised only against a disposable issue.

The tool-selection eval needs a model credential and spends money, so it is run deliberately:

uv run python evals/run_eval.py

Architecture:

agent -> stdio -> MCPServer -> JiraClient -> httpx2.AsyncClient -> Jira REST v3

One asynchronous HTTP client is reused for the process lifetime, with an explicit timeout and bounded retries — a 429 is retried for any method, a 5xx or a dropped connection only for methods that converge on replay, never a POST. JiraClient knows nothing about MCP; the tools are thin adapters over it.

Release model

Semantic versioning, Conventional Commits, short-lived branches, pull-request CI, and tagged releases. CHANGELOG.md records what changed for someone running the server. v0.1.0 is a GitHub Release with CI-checked wheel and source distributions attached. Starting with the next tag, the release workflow also publishes to PyPI using GitHub Actions Trusted Publishing (OIDC), with no long-lived credential to manage.

License

MIT. Not an official Atlassian product.