jira-mcp

A Model Context Protocol server for Jira Cloud. Create issues and subtasks, read issues, search with JQL, walk agile boards and their swimlanes, move issues through their workflow, comment, and attach files.

Authenticates with an Atlassian account email and an API token, so it runs headless — no OAuth, no browser round-trip, no interactive consent.

Install

Nothing to install. Point your MCP client at the package and let npx fetch it:

{
  "mcpServers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:skurekjakub/jira-mcp#v1.0.0"],
      "env": {
        "NPM_CONFIG_ALLOW_GIT": "root",
        "JIRA_SITE": "your-team.atlassian.net",
        "JIRA_CLOUD_ID": "00000000-0000-0000-0000-000000000000",
        "JIRA_PROJECT_KEY": "ABC",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    }
  }
}

The build artifact is committed and the runtime dependencies are inlined into it, so installing clones and links — no build step, no packages fetched, and no install script to approve.

NPM_CONFIG_ALLOW_GIT

npm 12 defaults allow-git to none, so without this npm refuses the install with EALLOWGIT — "Fetching packages of type git have been disabled". Setting it in the server's env block scopes the exemption to this one subprocess, which leaves git fetching disabled for every other install on the machine. root permits it for the package being installed but not for anything it might depend on; all lifts the restriction entirely and is not needed here. On npm 11 and older the variable is ignored.

Installing once instead

npx re-resolves the git ref on every start, which costs a few seconds and a network round-trip. To avoid both:

npm install -g --allow-git=root github:skurekjakub/jira-mcp

then use "command": "jira-mcp" with no args and no NPM_CONFIG_ALLOW_GIT. Upgrading is then a manual re-run of that command.

Configuration

Every setting comes from the environment. There is no config file, and the server reads no .env — an MCP client passes these in the env block above.

Find your cloud id with:

curl -s https://your-team.atlassian.net/_edge/tenant_info

Keeping the token out of version control

A committed MCP config must not contain the token itself. Claude Code expands ${VAR} references in command, args, env, url, and headers, so the config names a variable and the value lives elsewhere — a shell profile, or a settings file that is not committed.

A reference that nothing expands is not an error: Claude Code passes the literal text ${JIRA_API_TOKEN} through to the server. This server rejects a value of that shape at startup and names the variable, rather than sending it to Jira and returning an opaque 401.

Tools

jira_create_issue

Create an issue in JIRA_PROJECT_KEY.

jira_create_subtask

Create a subtask under an existing issue.

jira_get_issue

Fetch an issue's summary, description, type, status, parent, subtasks, issue links, and fix versions.

jira_search_issues

Search with JQL, paginated.

jira_get_board

Report an agile board's layout — columns, quick filters, and swimlanes, each with its JQL. Run it before jira_board_issues to learn the names that tool accepts. The board id is the boards/<id> segment of a board URL.

Swimlanes come from GreenHopper's internal API; Atlassian publishes no supported endpoint for them.

jira_board_issues

List the issues currently on a board, grouped by swimlane. Reproduces the board view: the board's own filter, its kanban sub-filter, any quick filters named, and extra JQL.

Each issue lands in exactly one swimlane — the first, in board order, whose query matches it. Requesting a subset of swimlanes still evaluates the lanes above them, so their claim on an issue holds.

jira_list_transitions

List the workflow transitions currently available on an issue. Transition names and ids are workflow-specific — call this before jira_transition_issue.

jira_transition_issue

Move an issue through its workflow. Matches transitionName case-insensitively against the issue's available transitions; fails with the valid list if nothing matches.

jira_add_comment

Add a comment. The body uses Jira wiki markup (h3. for headings, {{code}} for inline code, {code:lang}…{code} for blocks, bq. for blockquotes). Use real newlines, not literal \n escapes.

jira_add_attachment

Attach a file. The file must sit in JIRA_ATTACHMENTS_DIR; a name escaping that directory is refused.

Transports

stdio by default. --transport http --port <n> serves the same tools over a stateless Streamable HTTP transport at /mcp, with a health check at /health.

Development

npm install
npm test          # vitest
npm run lint      # tsc --noEmit
npm run build     # webpack -> dist/bundle.js

dist/bundle.js is committed so installs need no build step. CI rebuilds it on every push to main and commits the result, so it cannot drift from src/.

License

MIT