jira-mcp

MCP server for Jira Cloud over the REST API v3, authenticated with an API token.

Why it exists

Atlassian's hosted MCP server works for most calls, but these gaps showed up in daily use:

• Attachments cannot be read. An issue comes back with attachment metadata and blob: placeholders in the description, and the image bytes never arrive; the only way to see a screenshot was to open the issue in a browser. This server downloads an attachment to a local file and returns the path.

• It runs on a service you do not control. The hosted connector has hung for minutes on ordinary calls, and its OAuth tokens live on the hosting side, so a local script cannot reuse them. This server is a local process that talks to Jira directly.

• Mentions do not notify. With contentFormat: "markdown", [~accountid:X] is escaped to literal text and the person gets no notification; only an ADF mention node works. Here a text body takes @[accountId], @[accountId|Display Name] or [~accountid:X] and sends a real mention node, looking the display name up when it is not given; text without a marker stays plain text. dry_run returns the generated ADF without posting.

• Transition ids drift, and some statuses are two steps away. The same logical step can have different ids on different issue types and from different statuses, so an id taken from one issue fails on another, and a target status may only be reachable through an intermediate one. jira_transition_to_status takes a target status, plans the path, looks each step's transition up on the issue when it gets there (nothing is cached), and returns the final status and assignee; with no path it fails with the transitions that are available. dry_run shows the path. jira_transition stays as the low-level one-step call.

• Responses overflow the context. An issue with a long comment thread comes back too large to read, and every user carries four avatar sizes. Output here is compact by default: people as name and account id, the last N comments as author, date and text, the changelog as date · who · field: from → to lines, attachments as id, filename, size and type. Jira's full JSON only with raw: true.

• Smaller workarounds:

  • A worklog started with +02:00 is rejected, and the error names a Java date pattern rather than the colon. Here started accepts +02:00, Z or no offset and is sent as +0200.

  • A written description or comment can read back correctly through the fields API while the page renders it broken, for example a numbered list turned into headings. Writes here return the rendered HTML, and jira_get_issue has format: "html".

  • Each hosted worklog call returns about 1.5 KB, so posting many of them needed a separate script. Here worklogs are compact and do not notify watchers unless asked.

Related MCP server: jira-mcp

Tools

In jira_get_issue output an inline image appears as [image: attachment <id>], the id to pass to jira_download_attachment.

With readOnly set, the tools that write (comment, edit, transition, worklog, link) are not offered.

Install

Needs Node 18 or newer.

npm install

Register the server with your MCP client as stdio: command node, argument the full path to index.js.

Config

config.json next to index.js (gitignored; start from config.example.json), or the matching environment variables. A value left at an example placeholder counts as absent.

The token acts as your account, with all of its permissions. Keep it out of the repository.

Tests

npm test

Covers the text-to-ADF conversion (mentions above all), the path planning between statuses, the worklog time format and the image ids in rendered HTML.

Path planning

The path comes from the issue's workflow (POST /rest/api/3/workflows for its project and issue type). Many sites allow that read to administrators only; without it the tool still takes a direct transition, or follows the statuses given in via, and otherwise fails with the transitions available from the current status. If a post-function moves the issue somewhere other than the expected next status, the rest of the path is planned again from where it landed.

Backlog

Not in v1: creating issues, uploading attachments, editing or deleting comments and worklogs, listing worklogs, remote links, boards and sprints, and headings or tables in the text body form (pass raw ADF for those).