jira-mini-mcp

<div align="center">

# jira-mini-mcp

A Jira Cloud MCP server for coding agents: 6 read tools, 9 with writes enabled.

[![CI](https://github.com/proprock/jira-mini-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/proprock/jira-mini-mcp/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/proprock/jira-mini-mcp)](https://github.com/proprock/jira-mini-mcp/releases)
[![PyPI Version](https://img.shields.io/pypi/v/jira-mini-mcp)](https://pypi.org/project/jira-mini-mcp/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

[![Model Context Protocol compatible](https://img.shields.io/badge/Model_Context_Protocol-compatible-000000?logo=modelcontextprotocol&logoColor=white)](https://modelcontextprotocol.io)
[![MCP Registry: io.github.proprock/jira-mini-mcp](https://img.shields.io/badge/MCP_Registry-io.github.proprock%2Fjira--mini--mcp-000000?logo=modelcontextprotocol&logoColor=white)](server.json)
[![Auth: API token](https://img.shields.io/badge/Auth-API_token-2EBC4F)](#configure)

<img src="https://raw.githubusercontent.com/proprock/jira-mini-mcp/master/images/swiss-army-knife.jpg" alt="One job. One tool. Done right." width="760">

<i>One job. One tool. Done right.</i>

</div>

<!-- mcp-name: io.github.proprock/jira-mini-mcp -->

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; see
  [why so few](#why-so-few-tools) and how it's [compared with the
  alternatives](#compared-with-the-alternatives).
- **Read-only mode built in** - set one variable and the three write tools
  never register, not even as a disabled entry the agent can see.
- **Compact, predictable output** - stable JSON schemas, Markdown for rich
  text, no `null` spam, no second human-readable rendering of the same
  result; see [what the tools return](#what-the-tools-return).
- **On PyPI** - `uvx jira-mini-mcp` or `pip install jira-mini-mcp`, no repo
  clone or git URL required.

| Tool | Access | Purpose |
|---|---|---|
| `search_issues` | 🟢 read | Find issues with JQL |
| `get_issue` | 🟢 read | One issue's core state and fields |
| `get_comments` | 🟢 read | Recent or historical discussion, paginated |
| `get_attachments` | 🟢 read | Attachment metadata |
| `download_attachment` | 🟢 read | Fetch one attachment |
| `get_changelog` | 🟢 read | Field-change history, paginated |
| `add_comment` | 🔴 write | Post one Markdown comment |
| `transition_issue` | 🔴 write | Move an issue through its workflow |
| `update_issue` | 🔴 write | Set issue fields |

> [!TIP]
> Set `READ_ONLY_MODE=true` and only the six 🟢 read tools register - the
> three 🔴 write tools are withheld entirely, see [Configure](#configure).

- [Install](#install)
- [Configure](#configure)
- [What the tools return](#what-the-tools-return)
- [Writing to Jira](#writing-to-jira)
- [Examples](#examples)
- [Why so few tools](#why-so-few-tools)
- [Compared with the alternatives](#compared-with-the-alternatives)
- [Development](#development)
- [Release model](#release-model)

## Install

```bash
uvx jira-mini-mcp
```

or

```bash
pip install jira-mini-mcp
```

Pin a version when you want a fixed surface: `uvx jira-mini-mcp==0.9.0`.

Running an unreleased commit straight from GitHub also works:

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

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/) (or `pip`).

## Configure

Three required values, and one optional switch:

| Variable | Required | Meaning |
|---|---|---|
| `JIRA_BASE_URL` | yes | Your site, e.g. `https://example.atlassian.net` |
| `JIRA_EMAIL` | yes | The email your API token belongs to |
| `JIRA_API_TOKEN` | yes | A [Jira Cloud API token](https://id.atlassian.com/manage-profile/security/api-tokens) |
| `READ_ONLY_MODE` | no | `true`, `1`, `on` registers only the six read tools |

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.

<details>
<summary><b>Claude Code</b></summary>

```bash
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-mcp
```

Put 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.

</details>

<details>
<summary><b>Claude Desktop</b></summary>

In `claude_desktop_config.json`:

```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"
      }
    }
  }
}
```

</details>

<details>
<summary><b>Codex CLI</b></summary>

```bash
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-mcp
```

</details>

<details>
<summary><b>Any other stdio host</b></summary>

Command `uvx`, argument `jira-mini-mcp`, and the three environment variables.
Add `READ_ONLY_MODE=true` to withhold the write tools.

</details>

## 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:

```text
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:

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

`get_issue` defaults to these sixteen fields:

```text
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](https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issue-search/)
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:

```text
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