⚡ JIRA-MCP

A deployment-agnostic Jira MCP server over stdio — works with Jira Server, Data Center and Cloud with zero hardcoded board IDs, project keys, status names or customfield IDs.

╔══════════════════════════════════════════════════════════╗ ║ 📦 Compact output · issue cards, not raw payloads ║ ║ 🧠 Semantic actions · transition by status name ║ ║ 📋 Full board support· boards, backlog, sprints ║ ╚══════════════════════════════════════════════════════════╝

🎯 Why this package

Raw Jira REST payloads are enormous — every issue drags avatars, schemas, changelogs, expand lists and renderer metadata into your LLM's context window. This server projects each issue into a ~230 byte card, cutting context cost by ~99% while keeping every field an agent actually needs.

Measurement context (measured values): Jira Server/DC instance, Scrum board (boardId: 10212), jira_get_board_backlog with maxResults=25 — 25 issue cards from the real response, ~230 bytes per issue on average. The raw-payload column has no measured baseline for this instance: it uses the typical v2 search response size of ~40 KB per issue, so those numbers are labeled typical, not measured. Card fields used in the measurement: key, summary, type, status, assignee, priority, labels, parent, updated.

An example card from that measurement, verbatim:

{
  "key": "KAPI-215",
  "summary": "Sync servisindeki OPA güncelleme yeteneğin Kapı tarafından sağlanması",
  "type": "Task",
  "status": "Resolved",
  "assignee": "Barış Buğra ÖZDEMİR",
  "priority": "Medium",
  "labels": [],
  "parent": null,
  "updated": "2026-10-02"
}

Run it yourself with npm run benchmark -- "<your JQL>" — numbers depend on your instance, fields and issue size.

Related MCP server: Issue Tracker MCP

✨ Features (24 tools)

🔍 Discovery

📖 Reading

(also: jira_get_board_issues — issues currently on a board, jira_get_sprint_issues — issues of one sprint)

✍️ Writing

⏱️ Time & Links

🏃 Sprint

📥 Installation

1 · Run directly with npx (recommended):

npx @nevzatcirak/jira-mcp

2 · Install globally:

npm install -g @nevzatcirak/jira-mcp
jira-mcp

3 · From source:

git clone https://github.com/nevzatcirak/jira-mcp.git
cd jira-mcp
npm install && npm run build
node dist/index.js

Doğrulama:

jira-mcp --version
# @nevzatcirak/jira-mcp 1.0.1

🔁 Migrating from other jira-mcp packages

If a different jira-mcp package was installed earlier — one that registers the same jira-mcp bin name — a global install of this package fails with an EEXIST error. Find and remove the old package first:

# unix
npm ls -g | grep jira
npm rm -g <old-package-name>

# Windows (PowerShell)
npm ls -g | findstr jira
npm rm -g <old-package-name>

If a leftover bin shim remains, check which package it points to with where jira-mcp (Windows) or which -a jira-mcp (unix).

MCP clients that run the server through npx (the recommended setup) are not affected by this conflict — npx resolves the package by full name and does not use the global bin shim.

🩺 Troubleshooting

npx crashes on every run. Corrupted npx cache. Delete the cached package folder and npx re-downloads it on the next run:

• Windows: %LocalAppData%\npm-cache\_npx

• unix: ~/.npm/_npx

Windows: remote npx invocation fails ("not recognized"). On Windows, the short remote form npx -y @nevzatcirak/jira-mcp --version can fail with a "not recognized" error, while the same command works on unix. This is known npx behavior on Windows, not a package defect. Use one of these workarounds:

• Install globally and run the bin: npm i -g @nevzatcirak/jira-mcp then jira-mcp

• Pass the package and bin separately: npx -y -p @nevzatcirak/jira-mcp jira-mcp

• Skip the shim entirely — call the entry point with node in your MCP client config: node <install-path>/dist/index.js

The old 6-tool server still seems to run. A leftover global bin shim may still resolve to the old package. Check which package the shim points to with where jira-mcp (Windows) or which jira-mcp (unix), remove the old package (npm rm -g <old-package>), then reinstall this one.

"The backlog is not available on Kanban boards" Jira platform restriction: the backlog endpoint exists only on Scrum boards. For a Kanban board, use jira_get_board_issues with a JQL filter instead.

⚙️ Configuration

Server/DC vs Cloud authentication:

Config problems never crash the server — the tool call fails with a structured CONFIG_MISSING error listing the missing fields.

🔌 MCP client configuration

OpenCode (opencode.json)

{
  "mcp": {
    "jira": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@nevzatcirak/jira-mcp"
      ],
      "environment": {
        "JIRA_BASE_URL": "https://acme-jira.example.com",
        "JIRA_API_TOKEN": "your-personal-access-token",
        "JIRA_INSTANCE_TYPE": "server"
      }
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@nevzatcirak/jira-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://acme-jira.example.com",
        "JIRA_API_TOKEN": "your-personal-access-token",
        "JIRA_INSTANCE_TYPE": "server"
      }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@nevzatcirak/jira-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://acme-jira.example.com",
        "JIRA_API_TOKEN": "your-personal-access-token",
        "JIRA_INSTANCE_TYPE": "server"
      }
    }
  }
}

☁️ Cloud: add "JIRA_EMAIL": "you@example.com", set JIRA_INSTANCE_TYPE to cloud (or leave auto), and use an API token from id.atlassian.com.

🧪 Tool usage examples

1 · Pull a board backlog:

{ "tool": "jira_get_board_backlog", "arguments": { "boardId": 42, "maxResults": 25 } }

2 · JQL search with extra fields:

{ "tool": "jira_search_issues", "arguments": { "jql": "project = ABC AND status != Done ORDER BY updated DESC", "fields": ["storypoints"], "maxResults": 25 } }

3 · Issue details with comments:

{ "tool": "jira_get_issue", "arguments": { "issueKey": "ABC-123", "includeComments": true } }

4 · Log work:

{ "tool": "jira_add_worklog", "arguments": { "issueKey": "ABC-123", "timeSpent": "3h 30m", "comment": "Implemented retry logic and tests" } }

5 · Attach a web link:

{ "tool": "jira_add_remote_link", "arguments": { "issueKey": "ABC-123", "url": "https://design.example.com/spec-7", "title": "Design spec" } }

6 · Semantic transition (no transition IDs needed):

{ "tool": "jira_transition_issue", "arguments": { "issueKey": "ABC-123", "toStatus": "Done", "comment": "Verified on staging" } }

7 · Move issues into a sprint:

{ "tool": "jira_move_issues_to_sprint", "arguments": { "sprintId": 318, "issueKeys": ["ABC-123", "ABC-124", "ABC-125"] } }

8 · Find a user, then assign:

{ "tool": "jira_find_user", "arguments": { "query": "Jane Doe" } }

{ "tool": "jira_assign_issue", "arguments": { "issueKey": "ABC-123", "assignee": "jdoe" } }

📝 Behavior notes

Card projection. Every list/search result is a compact card — never avatars, schemas, changelogs or raw payloads:

{
  "key": "ABC-123",
  "summary": "Fix login redirect loop",
  "type": "Bug",
  "status": "In Progress",
  "assignee": "jdoe",
  "priority": "High",
  "labels": ["backend", "auth"],
  "parent": "ABC-100",
  "updated": "2026-01-14"
}

Extra fields can be merged in via fields (deduplicated; *all/*navigable are dropped on list endpoints).

Pagination. All paginated tools return top-level meta:

{ "total": 120, "startAt": 0, "maxResults": 25, "hasMore": true, "nextStartAt": 25 }

Keep passing startAt: nextStartAt until hasMore is false.

Truncation rules.

• Issue descriptions: capped by maxDescriptionChars (default 500, max 20000)

• Comments / worklog bodies in jira_get_issue: 500 chars each, capped at 1000 items

• Worklog comments in jira_list_worklogs: 300 chars

• Every truncated item reports { "truncated": true, "totalLength": 4211 }

• maxResults is hard-capped at 100 on every list tool

Structured errors. Failures never throw raw stack traces — every error is a structured payload:

{
  "error": {
    "code": "JIRA_400",
    "message": "Jira HTTP 400: ...",
    "hint": "parentKey may be rejected for Cloud team-managed projects...",
    "jiraErrors": {
      "errorMessages": ["Issue does not exist or you do not have permission to see it."],
      "errors": { "assignee": "User 'jdoe' does not exist." }
    }
  }
}

Fixed codes include CONFIG_MISSING, INVALID_ARGUMENT, JIRA_TIMEOUT, JIRA_NETWORK, AMBIGUOUS_TRANSITION, TRANSITION_NOT_FOUND, USER_NOT_FOUND, AMBIGUOUS_USER, FILE_TOO_LARGE. Jira's own field errors are preserved verbatim in jiraErrors.

Resilience. 30s per-request timeout, up to 2 retries on 429/5xx with Retry-After awareness, and an automatic agile/1.0 → greenhopper/1.0 fallback for older Server instances.

🛠️ Development

npm install          # install dependencies
npm test             # unit tests (vitest, no Jira connection needed)
npm run build        # compile to dist/
npm run lint         # eslint
npm run benchmark    # payload-size benchmark (needs a live Jira)

Integration tests (optional, against a real instance):

🚀 Publishing

Releases are published to npm automatically by CI — never publish manually from a laptop.

Flow:

1. Release workflow (.github/workflows/release.yml, manual workflow_dispatch): give it a semver version (e.g. 1.0.1) — it bumps package.json + package-lock.json, commits as github-actions[bot] with chore: release vX, creates tag vX and pushes both.

2. The v* tag push triggers the Publish workflow (.github/workflows/publish.yml), which runs tests + build and then npm publish --access public to https://registry.npmjs.org/.

One-time setup (required):

• Create an npm automation token with Read & Write permission at npmjs.com → Access Tokens (Classic Tokens section).

• Add it as a repository secret: GitHub repo → Settings → Secrets and variables → Actions → New repository secret, name it NPM_TOKEN.

• The publish job uses registry-url: https://registry.npmjs.org/ and passes the token via NODE_AUTH_TOKEN.

Guards (the publish job fails fast on):

• Version ↔ tag mismatch: package.json version must match the pushed tag (v + version, e.g. version 1.0.0 ↔ tag v1.0.0).

• Package name check: package.json name must be exactly @nevzatcirak/jira-mcp — prevents accidentally publishing the wrong package.

📌 Scoped package note: @nevzatcirak/jira-mcp is a scoped package, so npm publish --access public is mandatory (scoped packages default to restricted, which requires a paid plan).

🖐️ Manual dispatch note: the Publish workflow also supports workflow_dispatch, but a manual run skips the tag guard — it publishes whatever version is currently in package.json (tests + build still run). Prefer the Release workflow so tags and versions stay in sync.

📄 License

MIT © Nevzat Cirak