jira-mcp

An MCP (Model Context Protocol) server that exposes the Jira REST API to AI assistants — boards, sprints, epics, issues, JQL search, workflow transitions, comments, worklogs, projects, users, plus a generic passthrough tool for any Jira REST endpoint.

Works with both Jira Cloud (REST API v3) and Jira Data Center (REST API v2), auto-detected from the base URL.

Install (one-click)

Once published to npm, any MCP client can run it via npx — no local build needed.

Interactive installer (all agents at once)

npx -y @thammarongg/jira-mcp@latest install

Shows a menu — Select All or pick agents (Claude Code, OpenCode, Codex, Cursor, Claude Desktop, Gemini CLI) — then asks for the Jira base URL and credentials (token entry is masked on a TTY). If a selected agent already has a jira entry, the installer offers to reuse its base URL and account without asking for the credentials again. Existing config files are backed up to .bak before any modification, and re-running updates the jira entry in place instead of duplicating it.

With --yes and no credential flags, a selected existing entry's credentials are reused without prompting.

Non-interactive (CI / scripting):

# Jira Cloud
npx -y @thammarongg/jira-mcp@latest install --agents all \
  --base-url https://your-org.atlassian.net \
  --email [email protected] --token xxx --yes

# Jira Data Center (subset of agents)
npx -y @thammarongg/jira-mcp@latest install --agents claude-code,codex \
  --base-url https://jira.yourcompany.com \
  --username you --token xxx --yes

Flags: --agents all or comma-separated ids/numbers (claude-code, opencode, codex, cursor, claude-desktop, gemini-cli), --base-url, --email (Cloud) / --username (Data Center), --token (API token or PAT), --password (DC app password), --yes (skip the confirm prompt).

CLI commands

npx -y @thammarongg/jira-mcp@latest update                 # refresh configured agents
npx -y @thammarongg/jira-mcp@latest update --agents codex
npx -y @thammarongg/jira-mcp@latest uninstall              # choose configured agents interactively
npx -y @thammarongg/jira-mcp@latest uninstall --agents all --yes
npx -y @thammarongg/jira-mcp@latest --version
npx -y @thammarongg/jira-mcp@latest --help

update is non-interactive and repairs every existing jira entry from that agent's own credentials; agents without an entry are skipped. uninstall removes only the jira entry, preserving the rest of each agent configuration; it accepts the same --agents selection grammar as install and asks for confirmation unless --yes is supplied.

Running npx -y @thammarongg/jira-mcp@latest bare in a terminal prints a status card with the installed version, configured agents, and available commands. MCP clients pipe stdio, so the same bare command starts the MCP server for them; it expects JIRA_* environment variables, which is why running it bare without those variables reports a missing JIRA_BASE_URL.

Claude Code (manual one-liner)

claude mcp add jira --env JIRA_BASE_URL=https://your-org.atlassian.net \
  --env [email protected] --env JIRA_API_TOKEN=xxx \
  -- npx -y @thammarongg/jira-mcp@latest

// Claude Desktop / any MCP client (mcpServers)
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@thammarongg/jira-mcp@latest"],
      "env": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "xxx"
      }
    }
  }
}

// opencode (opencode.json)
{
  "mcp": {
    "jira": {
      "type": "local",
      "command": ["npx", "-y", "@thammarongg/jira-mcp@latest"],
      "environment": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "xxx"
      },
      "enabled": true
    }
  }
}

Publishing

npm login
npm publish          # prepublishOnly runs build + smoke test first

Local development (no publish)

npm install
npm run build
# run directly: node dist/index.js  (or `npm run dev` via tsx)

Configuration (environment variables)

| Variable | Required | Description | | --- | --- | --- | | JIRA_BASE_URL | yes | https://your-org.atlassian.net (Cloud) or https://jira.yourcompany.com (DC); a DC context path such as /jira is preserved | | JIRA_EMAIL | Cloud | Your Atlassian account email | | JIRA_API_TOKEN | yes | API token (Cloud: id.atlassian.com → Security → API tokens; DC: personal access token) | | JIRA_USERNAME | DC | Username (alternative to JIRA_EMAIL) | | JIRA_PASSWORD | DC | App password (alternative to JIRA_API_TOKEN) | | JIRA_API_VERSION | no | Force 2 or 3. Default: auto (Cloud → 3, DC → 2) | | JIRA_TIMEOUT_MS | no | Request timeout, default 30000 |

Quick auth check:

JIRA_BASE_URL=... JIRA_EMAIL=... JIRA_API_TOKEN=... node dist/index.js

Then call the get_current_user tool from your MCP client — it verifies credentials.

Using a local checkout

Prefer not to publish? Point the client at the built file instead of npx — same env vars as above:

claude mcp add jira --env JIRA_BASE_URL=https://your-org.atlassian.net \
  --env [email protected] --env JIRA_API_TOKEN=xxx \
  -- node /absolute/path/to/jira-mcp/dist/index.js

// opencode (opencode.json)
{
  "mcp": {
    "jira": {
      "type": "local",
      "command": ["node", "/absolute/path/to/jira-mcp/dist/index.js"],
      "environment": {
        "JIRA_BASE_URL": "https://your-org.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "xxx"
      },
      "enabled": true
    }
  }
}

Agent skill

A ready-made agent skill (setup + workflow guidance for the tools) ships in skill/SKILL.md. Install it by copying to your skills directory:

mkdir -p ~/.claude/skills/jira && cp skill/SKILL.md ~/.claude/skills/jira/
# or for opencode / shared agents:
mkdir -p ~/.agents/skills/jira && cp skill/SKILL.md ~/.agents/skills/jira/

Tools

Boards & sprints (Agile + Software APIs)

| Tool | Description | | --- | --- | | list_boards | List boards (filter by type/name/project key or ID) | | get_board | Board details incl. projects | | list_sprints | Sprints on a board (state: active/closed/future) | | get_sprint | Sprint details | | create_sprint | New sprint on a board | | update_sprint | Rename, reschedule, change goal/state | | close_sprint | Close a sprint | | get_sprint_issues | Issues in a sprint (Cloud cursor or DC offset paging) | | get_sprint_view | Full UI-like sprint view (board + sprint + issues in one call) | | get_backlog | Board backlog (Cloud Software enhanced or DC Agile, rank-ordered) |

Epics

| Tool | Description | | --- | --- | | list_epics | Epics on a board (optionally filtered by done) | | get_epic / get_epic_issues | Read an epic and its children (works on team-managed projects) | | create_epic | New epic in a project | | move_issue_to_epic | Add issues to an epic (sets parent on team-managed) | | get_epic_meta | Epic-level issue types available in a project |

Issues

| Tool | Description | | --- | --- | | get_issue | Issue by key | | create_issue | Create (supports custom fields) | | update_issue | Set fields and/or relative update ops | | delete_issue | Delete | | search_issues | JQL search — enhanced search (/search/jql) on Cloud, legacy /search on Data Center | | get_issue_create_meta | Discover projects/types/required fields (current per-project metadata endpoints) | | get_issue_transitions / transition_issue | Workflow transitions | | assign_issue | Assign/unassign | | add_comment / list_comments / delete_comment | Comments (plain text in, auto-converted to ADF on Cloud/v3) | | get_issue_worklogs / add_worklog | Time tracking |

Projects, users, meta

list_projects, get_project, get_project_components, create_project_component, get_project_issue_types, get_project_roles, get_project_versions, get_current_user, find_users, get_user, get_fields, get_issue_types

Escape hatch

| Tool | Description | | --- | --- | | jira_api | Raw call to any /rest/... endpoint (method, path, query, body) — covers the full Jira REST API |

Typical agent workflow

1. list_boards → pick a board
2. list_sprints (state: active) → pick a sprint
3. get_sprint_issues or get_sprint_view → see the work
4. search_issues with JQL for anything custom
5. create_issue / transition_issue / add_comment to act
6. Anything else → jira_api

Rich text and ADF

Jira Cloud REST v3 stores descriptions, comment bodies and worklog comments as Atlassian Document Format, not plain strings. Pass plain text to create_issue, create_epic, update_issue, transition_issue, add_comment and add_worklog — the server wraps it in ADF when JIRA_API_VERSION is 3, and leaves it alone on v2 (Data Center), where wiki markup applies. Blank lines start a new paragraph and single newlines become line breaks; Markdown is not rendered (**bold** shows literally). Already-built ADF objects are passed through untouched.

Development

npm run dev        # run from source via tsx
npm run build      # compile to dist/
npm run typecheck  # tsc --noEmit
node scripts/smoke.mjs   # stdio handshake + tools/list smoke test

Notes & limitations

• Auth is HTTP Basic (email+token for Cloud, username+token/password for DC) — the standard for Jira REST.
• JIRA_BASE_URL may include a Data Center context path (for example https://jira.example.com/jira); it is retained when resolving /rest/... endpoints.
• Pagination: most list tools return Jira's native startAt/maxResults/total; pass startAt to page.
• Platform routing: Cloud-only enhanced Software reads use /rest/software/1.0 for backlog, sprint issues, and epic issues (cursor nextPageToken); Data Center uses the corresponding Agile 1.0 endpoints with startAt/total. list_boards passes its project filter as the Agile API's singular projectKeyOrId parameter.
• create_sprint uses the documented top-level Agile POST /rest/agile/1.0/sprint route and sends the selected board as originBoardId.
• JQL search on Jira Cloud uses /rest/api/3/search/jql, since Atlassian removed GET /rest/api/{2,3}/search on 2025-05-01 (CHANGE-2046 — the old endpoint now returns HTTP 410). Consequences for search_issues on Cloud: the JQL must be bounded (include a restriction such as project, assignee, or key), the response carries no total, and paging is by cursor — pass the returned nextPageToken back and stop when isLast is true. startAt is rejected there rather than silently ignored, and includeApproximateTotal: true adds an approximate match count via /search/approximate-count.
• Jira Data Center keeps the legacy /search endpoint with startAt/total; if a Cloud site on a custom domain is misdetected as DC, a 410 from /search transparently retries against /search/jql.
• get_issue_create_meta composes the current per-project and per-issue-type metadata endpoints (/issue/createmeta/{project}/issuetypes and /issue/createmeta/{project}/issuetypes/{issueType}), because the old /issue/createmeta query form is deprecated on Cloud and removed from Jira Data Center 9.0+. Its output keeps the familiar projects[].issuetypes[].fields shape. Pass projectKeys when fields are expanded (the default); omitting it is allowed only with expand: "projects.issuetypes" for bounded issue-type summaries. Project metadata is fetched with a fixed concurrency of four, and issue-type field metadata is likewise limited to four concurrent requests.
• get_backlog, get_sprint_issues, and get_epic_issues use Cloud's current Software enhanced endpoints with cursor paging; pass nextPageToken for the next page. Data Center keeps Agile 1.0 and startAt/total. The older Cloud Agile issue-list endpoints remain available but are deprecated.
• Rapid view IDs are computed as boardId * 10^13 + sprintId (Jira's documented convention).
• Comment bodies use the body field on both Cloud (v3) and Data Center (v2).
• User references use accountId on API v3/Cloud and name on API v2/Data Center. get_user calls /user?accountId=... on v3; the v3 path form /user/{accountId} is not a current endpoint. create_issue's dueDate input is sent as Jira's duedate field; add_worklog accepts an optional started timestamp and Jira defaults it to now when omitted.
• Epics: the Agile epic API (/rest/agile/1.0/epic/...) only understands company-managed epics and returns HTTP 400 on team-managed ("next-gen") projects. get_epic, get_epic_issues, and move_issue_to_epic detect that and fall back to the issue/search APIs, where an epic is an ordinary issue linked to its children by parent.
• Jira Data Center exposes platform REST API v2/latest, not /rest/api/3. Leave JIRA_API_VERSION at its default (2) for DC; forcing 3 against a DC host is unsupported and causes the server to request unavailable /rest/api/3/... routes. Cloud-vs-DC endpoint routing is based on the detected deployment (*.atlassian.net is Cloud), while field representations are based on the selected API version.
• jira_api paths must resolve under /rest/ — paths that would escape it (e.g. via .. segments) are rejected, and ?/# must be passed via query.

License

MIT © Thammarong G.