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.

Variable	Required	Description
JIRA_SITE	yes	Site host, e.g. your-team.atlassian.net. A scheme and trailing slashes are accepted and stripped
JIRA_CLOUD_ID	yes	Tenant id — see below
JIRA_PROJECT_KEY	yes	Project jira_create_issue and jira_create_subtask write into
JIRA_EMAIL	yes	Atlassian account email the API token belongs to
JIRA_API_TOKEN	yes	API token, from Atlassian account settings
JIRA_ATTACHMENTS_DIR	no	Directory jira_add_attachment reads uploads from. Defaults to /tmp/mcp-attachments
JIRA_ISSUE_KEY	no	Pins jira_add_comment and jira_add_attachment to one issue and drops issueKey from their inputs

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.

Parameter	Type	Required	Description
summary	string	yes	Issue title
description	string	yes	Plain text, converted to ADF (paragraphs split on blank lines)
issueType	string	no	e.g. Task, Bug, Story (default Story)
labels	string[]	no	Optional labels
parentKey	string	no	Link under a parent, e.g. an epic — valid only if the project's issue-type hierarchy allows it

jira_create_subtask

Create a subtask under an existing issue.

Parameter	Type	Required	Description
parentKey	string	yes	Parent issue key, e.g. ABC-3200
summary	string	yes	Subtask title
description	string	no	Plain text, converted to ADF
labels	string[]	no	Optional labels

jira_get_issue

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

Parameter	Type	Required	Description
issueKey	string	yes	Issue key, e.g. ABC-3316
extraFields	string[]	no	Additional field ids (e.g. customfield_15000) returned raw under extra, keyed by field id

jira_search_issues

Search with JQL, paginated.

Parameter	Type	Required	Description
jql	string	yes	JQL query
maxResults	number	no	Page size, 1–100 (default 50)
nextPageToken	string	no	Token from a previous page
includeDescription	boolean	no	Include each issue's description, flattened to text
extraFields	string[]	no	Additional field ids returned raw under extra

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.

Parameter	Type	Required	Description
boardId	number	yes	Numeric board id, e.g. 1150

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.

Parameter	Type	Required	Description
boardId	number	yes	Numeric board id
swimlanes	string[]	no	Swimlane names or ids to return (case-insensitive). Omit for every swimlane
quickFilters	string[]	no	Quick-filter names or ids, ANDed together
jql	string	no	Extra JQL ANDed onto the board filter
applySubQuery	boolean	no	Apply the board's kanban sub-filter (default true)
maxIssuesPerSwimlane	number	no	Per-swimlane cap, 1–1000 (default 200). Each lane reports matched and truncated
keysOnly	boolean	no	Return only issue keys per swimlane (default false). Rejected together with extraFields
extraFields	string[]	no	Additional field ids returned raw per issue under extra

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.

Parameter	Type	Required	Description
issueKey	string	yes	Issue key

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.

Parameter	Type	Required	Description
issueKey	string	yes	Issue key
transitionName	string	yes	Target transition name, e.g. Done (case-insensitive)
resolution	string	no	Resolution to set — only needed if the transition's screen requires one
comment	string	no	Comment added as part of the transition

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.

Parameter	Type	Required	Description
body	string	yes	Comment body in Jira wiki markup
issueKey	string	conditional	Hidden when JIRA_ISSUE_KEY is set

jira_add_attachment

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

Parameter	Type	Required	Description
fileName	string	yes	Name of a file in the attachments directory
issueKey	string	conditional	Hidden when JIRA_ISSUE_KEY is set

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