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.

Related MCP server: Jira MCP Server

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

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

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