jira-mcp

An MCP server for Jira Server / Data Center, authenticating with a Personal Access Token (Bearer auth, REST API v2).

Built for research and analysis, not just ticket filing: read history, discover the custom fields an org actually uses, trace tickets to code, and aggregate across many issues to see how a workflow really behaves.

Targets Jira Server / Data Center, not Jira Cloud. Server/DC uses Bearer <PAT> auth and usernames; Cloud uses Basic auth with an API token and accountId.

Runs with zero dependencies. No npm install required — clone and run. Useful on locked-down machines where the npm registry is unreachable, and a much smaller audit surface if your security team has to approve it.

Tools

Core — read and write

Schema discovery — what fields and rules exist

History and traversal

Aggregate analysis

Related MCP server: jiraxmcp

Install as a plugin (recommended)

This repo is also a plugin: the 21 MCP tools plus two skills that teach Claude how to use them.

If your client accepts a plugin file (Claude Cowork and the desktop app do — they will tell you only packaged plugins are allowed), download jira-mcp.plugin from Releases and open it. It appears as a preview you can browse and accept. Build it yourself with:

npm run package:plugin     # -> dist/jira-mcp.plugin

If your client supports git marketplaces (Claude Code CLI):

/plugin marketplace add wyckit/jira-mcp
/plugin install jira-mcp@wyckit

Set your credentials as environment variables first — the plugin reads them from the environment, so no token is ever written into a config file or shared repo:

setx JIRA_BASE_URL "https://your-jira-host"
setx JIRA_PAT "your-personal-access-token"

setx only affects new processes, so restart your terminal and Claude Code afterward.

Or use a config file instead, if environment variables are awkward. Create .jira-mcp.json in your home folder:

{ "baseUrl": "https://your-jira-host", "pat": "your-personal-access-token" }

Searched in order — first hit wins, and environment variables always take precedence:

The startup banner reports which source was used (never the value):

jira-mcp v2 connected — https://your-jira-host (runtime: lite, credentials: C:\Users\you\.jira-mcp.json)

Do not put the token in the plugin's .mcp.json. That file ships inside the distributable .plugin, so a token written there travels to everyone you share it with. The locations above are deliberately outside the packaged artifact, and the packager refuses to build if it finds a literal credential in any file it would include.

The plugin works with or without Node

The plugin launches through bin/jira-mcp.cmd, which resolves a runtime at startup:

So a machine with no Node at all gets the full plugin — skills included — by downloading jira-mcp.exe from Releases and setting JIRA_MCP_EXE to its path. If none of the three resolve, the launcher writes no runtime found to stderr rather than failing silently.

The launcher is a Windows batch file, since the standalone executable is Windows-only. bin/jira-mcp.sh is the POSIX equivalent — on macOS or Linux, change the plugin's .mcp.json command to sh with that script as its argument.

To develop or test locally without installing:

claude --plugin-dir /path/to/jira_mcp

What the skills add

MCP gives Claude the tools. The skills give it the judgment for using them — they load only when relevant, so they cost nothing until they're needed.

jira-research exists because the failure mode of Jira analysis is confident wrong answers: someone guesses a JQL query, gets a plausible list, and reports a correlation as a cause. The skill encodes the ordering that prevents that.

Install manually

Pick the row that matches what the target machine allows.

Option A — standalone executable (no Node, no install)

Download jira-mcp.exe from the latest release, put it anywhere (a user folder is fine), and point Claude Code at it:

claude mcp add jira --scope user -e JIRA_BASE_URL=https://your-jira-host -e JIRA_PAT=YOUR_TOKEN -- C:/path/to/jira-mcp.exe

Nothing is installed — no admin rights, no registry writes, no PATH changes, no Node. It's one file you copy and run. About 88 MB, because Node's runtime is embedded in it.

Two caveats worth knowing up front. The binary is unsigned, so SmartScreen may warn on first run and environments enforcing AppLocker or WDAC may refuse to execute it — that's the one failure mode this option has, and it's a policy decision you can't work around locally. And it's Windows x64; rebuild on another platform with npm run build:exe for a native binary there.

Build it yourself instead of trusting a download:

npm run build:exe     # -> dist/jira-mcp.exe
npm run test:exe      # drives the binary against a local mock Jira

The build needs npm on the build machine only (for postject, Node's official blob injector). The resulting executable has no such requirement.

Option B — from source

Requires Node 18 or newer — that's the only prerequisite. Node 18 is when fetch became global, which is the one platform feature this server depends on.

git clone https://github.com/wyckit/jira-mcp
cd jira-mcp
node server.js          # already works — no install step

npm install is optional. It pulls in the official MCP SDK and zod, which the server prefers when present. Without them it falls back to the dependency-free implementation bundled in lib/. Both paths are covered by the same test suite (see Tests), and the startup banner on stderr tells you which one is active:

jira-mcp v2 connected — https://jira.example.com (runtime: lite)

runtime: lite is the bundled implementation, runtime: sdk is the official SDK. Force either one with JIRA_MCP_RUNTIME=lite or JIRA_MCP_RUNTIME=sdk.

If you can't use git either, downloading the repo zip works the same way — the only files needed at runtime are server.js and lib/.

Setup

1. Create a PAT in Jira: avatar (top right) → Profile → Personal Access Tokens → Create token. Copy it — it's shown once.

2. Register with Claude Code (--scope user makes it available in every project, not just the current folder):

   claude mcp add jira --scope user -e JIRA_BASE_URL=https://jira.example.com -e JIRA_PAT=YOUR_TOKEN_HERE -- node /absolute/path/to/jira_mcp/server.js

   Env var	Required	Purpose
   JIRA_BASE_URL	yes	Your Jira Server/DC base URL, e.g. https://jira.example.com
   JIRA_PAT	yes	Personal Access Token
   NODE_EXTRA_CA_CERTS	no	Path to a corporate root CA PEM, if TLS verification fails
   JIRA_MCP_RUNTIME	no	lite or sdk to force an implementation; defaults to auto-detect

3. Verify: restart Claude Code, then ask it to run jira_myself. It should return your Jira profile.

Tests

node test/run-tests.mjs     # or: npm test    — the library, no network
node test/run-exe-tests.mjs # or: npm run test:exe — the built binary, over HTTP

run-tests.mjs runs the tool surface against mocked Jira responses — no network, no credentials, no dependencies. Covers the changelog/duration math, rework detection, the transition graph, field fill rates, set comparison (including that per-issue noise fields stay filtered out), comment-thread text search, graph traversal, and schema default-filling. It runs twice when the SDK is installed — once on each runtime — so the dependency-free path is proven equivalent rather than assumed.

run-exe-tests.mjs starts a local HTTP server impersonating Jira, points dist/jira-mcp.exe at it, and drives the real MCP stdio protocol. This exercises the shipped binary over a real network stack, and asserts it sends Authorization: Bearer <PAT> correctly.

Both suites share their fixtures (test/fixtures.mjs), so the library and the executable are held to the same expected output.

How it works without dependencies

MCP over stdio is newline-delimited JSON-RPC 2.0, and tool schemas are plain JSON Schema. Neither needs a library:

server.js imports from lib/runtime.mjs and is identical on both paths — there is only one copy of the tool logic, so the two runtimes cannot drift.

A research workflow that works

Start broad, then narrow — don't open with a JQL guess:

1. jira_list_projects — find the project keys that matter.

2. jira_list_fields with a filter like environment, inventory, or release — learn what your org actually calls things. Do this before writing JQL; custom field names are the vocabulary everything else depends on.

3. jira_get_project_workflow and jira_get_create_meta — see the statuses and the rules on paper.

4. jira_analyze_workflow over ~90 days of tickets — see how the workflow behaves in practice, and where it diverges from the diagram.

5. jira_compare_issue_sets — contrast the tickets that made it to production against those that didn't.

6. jira_search_text — once the aggregates suggest a qualifier (a field, a flag, a check), mine descriptions and comments for where people actually discuss it. Comments are where the real rules get written down.

7. jira_get_issue / jira_get_changelog / jira_trace_graph / jira_get_dev_info on the handful of tickets the aggregates flagged — this is where actual understanding comes from.

The aggregate tools narrow the search space; they do not produce conclusions on their own. Treat what they surface as candidates to confirm by reading the tickets.

Notes

• The PAT is read from the environment at runtime and is never stored in this repo. Keep it in your MCP registration's env config — don't hardcode or commit it.

• Many self-hosted Jira instances sit behind a VPN or a WAF. If every call returns HTML or a 403 instead of JSON, you're most likely off-network — the server reports this explicitly rather than failing with a JSON parse error.

• PATs expire if you set an expiry when creating them; a 401 from every tool usually means the token expired.

• Analysis tools sample up to 300 issues and page through results. Each jira_analyze_workflow issue costs a changelog fetch, so start with the default sample size on a large project.

• jira_get_dev_info assumes Bitbucket (applicationType: "stash"). If your org links GitHub or GitLab instead, that tool needs a one-line change.

• Double-check your JIRA_BASE_URL spelling. A typo'd hostname can resolve to a parked domain owned by someone else, and your token goes to them in an Authorization header.

License

MIT