Jira MCP Server

Author: Ashish Kumar Kashyap (@akashyap3c)

A Model Context Protocol (MCP) server for Atlassian Jira Cloud. Manage projects, issues, sprints, boards, worklogs, comments, and workflow transitions from Cursor, Claude Code, or any MCP-compatible client.

---

Two ways to use this server

1. Use the hosted instance (recommended) — point your MCP client at https://mcp-jira-server.onrender.com/mcp with your own Jira credentials passed as headers. No install required. See below.
2. Self-host — clone the repo and run locally (stdio for one user) or deploy your own HTTP instance (Render, Fly, Docker, …). See Self-host.

Prerequisites

• Jira Cloud account (e.g. https://yourorg.atlassian.net)
• Atlassian API token — create one
• For self-host only: Node.js 18+

---

Use the hosted server (recommended)

A hosted instance is live at https://mcp-jira-server.onrender.com/mcp. You don't need to clone, install, or deploy anything — just point your MCP client at it with your own Jira credentials passed as request headers. Each user authenticates as themselves; no credentials are stored server-side.

Claude Code

Option A — CLI (writes the config for you):

claude mcp add --transport http --scope user jira-remote https://mcp-jira-server.onrender.com/mcp \
  --header "X-Jira-Base-Url: https://YOUR-DOMAIN.atlassian.net" \
  --header "X-Jira-Email: you@example.com" \
  --header "X-Jira-Token: YOUR_JIRA_API_TOKEN"

Option B — JSON (drop into ~/.claude.json under mcpServers, or a project-local .mcp.json):

{
  "mcpServers": {
    "jira-remote": {
      "type": "http",
      "url": "https://mcp-jira-server.onrender.com/mcp",
      "headers": {
        "X-Jira-Base-Url": "https://YOUR-DOMAIN.atlassian.net",
        "X-Jira-Email": "you@example.com",
        "X-Jira-Token": "YOUR_JIRA_API_TOKEN"
      }
    }
  }
}

Verify with claude mcp list — you should see jira-remote: ... (HTTP) - ✓ Connected.

Claude Desktop

Same JSON shape in claude_desktop_config.json (under mcpServers).

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "jira-remote": {
      "type": "streamable-http",
      "url": "https://mcp-jira-server.onrender.com/mcp",
      "headers": {
        "X-Jira-Base-Url": "https://YOUR-DOMAIN.atlassian.net",
        "X-Jira-Email": "you@example.com",
        "X-Jira-Token": "YOUR_JIRA_API_TOKEN"
      }
    }
  }
}

Supported headers

Header	Required	Purpose
X-Jira-Base-Url	yes	Your Jira Cloud base URL, e.g. https://yourorg.atlassian.net
X-Jira-Email	yes	The Atlassian account email
X-Jira-Token	yes	An Atlassian API token — create one
X-Jira-Read-Only	no	true to refuse non-GET/HEAD calls in jira_platform_request / jira_agile_request

Health check

curl https://mcp-jira-server.onrender.com/health
# {"status":"ok","server":"jira-mcp"}

The hosted server runs on Render's free plan, which sleeps after inactivity. The first request after sleep takes ~10–30 seconds to wake; subsequent calls are fast. For a production setup, self-host using the section below.

---

Self-host (run your own)

If you'd rather not depend on the hosted instance — for production, compliance, or a private network — run the server yourself.

Clone and install

git clone git@github.com:akashyap3c/jira-mcp.git
cd jira-mcp
npm install

Local stdio (single user, no network)

Best for solo use from one machine. The MCP client spawns the server as a subprocess and passes creds via env. No HTTP server runs.

Add to your MCP client config (replace the path with your absolute path):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/mcp-server/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

For stdio you can also test it standalone:

npm run mcp           # alias for: node mcp-server/index.js
# JIRA MCP server running on stdio

Local HTTP (multi-user, on your own host)

Run the HTTP server and have clients connect with per-user headers (same shape as the hosted instructions, just swap the URL).

npm start             # alias for: node mcp-server/http.js
# JIRA MCP server (HTTP) listening on port 3000

Clients then point at http://localhost:3000/mcp (or your own hostname/port) and pass X-Jira-Base-Url / X-Jira-Email / X-Jira-Token headers per request.

(Optional) For a stdio or shared-identity setup, copy .env.example to .env and set JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN. These are used only as a fallback when no X-Jira-* headers are present on a request.

Deploy to Render (or any platform)

This repo's render.yaml provisions a Web Service that runs npm start (HTTP transport) with a /health probe. To deploy your own copy:

1. Fork or push this repo to GitHub.
2. Render dashboard → New Web Service → connect your GitHub repo → Render reads render.yaml.
3. No env vars required if you want users to authenticate per-request via headers. The hosted instance runs this way.
4. (Optional) Set JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN env vars only if you want a fallback shared identity when headers are missing.

The included Dockerfile also works on:

• Fly.io: fly launch from the repo directory
• Railway: connect the GitHub repo → it auto-detects the Dockerfile
• Any VPS: docker build -t jira-mcp . && docker run -p 3000:3000 jira-mcp

---

API reference (PM / full REST surface)

• docs/API-REFERENCE.md — links to official Swagger, optional env vars, and how curated tools map to PM workflows.
• jira_platform_request / jira_agile_request — call any documented Platform or Agile endpoint (with path safety and optional read-only mode).

---

Available tools

Tool	Description
list_projects	List accessible Jira projects
get_issue	Get issue details by key
search_issues	Search issues using JQL
create_issue	Create a new issue (summary, description, priority, labels, original estimate, etc.)
update_issue	Update issue fields (summary, description, priority, labels, original estimate)
delete_issue	Permanently delete an issue (optional: delete subtasks)
assign_issue	Assign or unassign an issue (by accountId)
get_transitions	List available workflow transitions for an issue
transition_issue	Move an issue through a workflow (by transition ID)
add_comment	Add a comment to an issue
get_comments	List comments on an issue
log_work	Log time spent on an issue (worklog)
get_worklogs	List worklogs on an issue
get_link_types	List available issue link types (Blocks, Relates to, etc.)
link_issues	Link two issues with a relationship type
search_users	Search users by name/email (returns accountId for assign_issue)
list_boards	List Jira boards (ID, name, type)
list_sprints	List sprints for a board (paginated)
get_all_sprints	Get all sprints for a board with ID and name (auto-paginated)
get_sprint_issues	Get issues in a sprint
move_to_sprint	Move issues into a sprint (by sprintId or sprintName + boardId)
move_to_backlog	Move issues from a sprint back to the backlog
get_sprint	Sprint metadata by ID (dates, state, goal)
get_board_backlog	Board backlog issues (optional JQL)
get_board_issues	Board-scoped issues (optional JQL)
list_board_reports	Report types available for a board
aggregate_worklogs	Sum time logged by user across issues from JQL (capped)
list_board_epics	Epics on a board
get_epic_issues	Issues for an epic on a board
get_issues_without_epic	Board issues not under any epic
list_fields	All fields (find story points custom field ids)
list_filters	Search saved filters
get_filter	Get filter details and JQL by ID
sprint_metrics	Derived counts / story points by status category for a sprint
jira_platform_request	Low-level GET/POST/... under /rest/api/3
jira_agile_request	Low-level GET/POST/... under /rest/agile/1.0

---

Project structure

jira-mcp/
├── Dockerfile
├── mcp-server/
│   ├── index.js           # Entry point (stdio transport, local)
│   ├── http.js            # Entry point (HTTP transport, remote)
│   ├── jira-client.js     # Jira REST API (v3 + Agile 1.0)
│   ├── formatters.js      # ADF/plain text, markdown tables
│   └── tools/             # MCP tool handlers
│       ├── list-projects.js
│       ├── get-issue.js
│       ├── search-issues.js
│       ├── create-issue.js
│       ├── update-issue.js
│       ├── delete-issue.js
│       ├── assign-issue.js
│       ├── get-transitions.js
│       ├── transition-issue.js
│       ├── add-comment.js
│       ├── get-comments.js
│       ├── log-work.js
│       ├── get-worklogs.js
│       ├── get-link-types.js
│       ├── link-issues.js
│       ├── search-users.js
│       ├── list-boards.js
│       ├── list-sprints.js
│       ├── get-all-sprints.js
│       ├── get-sprint-issues.js
│       ├── move-to-sprint.js
│       ├── move-to-backlog.js
│       ├── get-sprint.js
│       ├── get-board-backlog.js
│       ├── get-board-issues.js
│       ├── list-board-reports.js
│       ├── aggregate-worklogs.js
│       ├── list-board-epics.js
│       ├── get-epic-issues.js
│       ├── get-issues-without-epic.js
│       ├── list-fields.js
│       ├── list-filters.js
│       ├── get-filter.js
│       ├── sprint-metrics.js
│       ├── jira-platform-request.js
│       └── jira-agile-request.js
├── docs/
│   └── API-REFERENCE.md
├── .env.example
├── package.json
└── README.md

---

License

MIT