Jira Scoped MCP server

mcp-jira-scoped

A Jira MCP server built around Atlassian's scoped API tokens, with scope enforcement in the server itself.

Most Jira MCP servers use classic (unscoped) API tokens with basic auth against yoursite.atlassian.net — including the most popular one, which still has scoped-token support open as a feature request. Atlassian is moving away from classic tokens. This server is built for scoped tokens against the modern api.atlassian.com gateway, and enforces your granted scopes server-side before any API call is made — the AI is never trusted to restrain itself.

v2.0 is a breaking change. Default content format is now Markdown, jirasearch paginates on nextPageToken instead of startAt, and an unrecognised JIRASCOPES value now fails at startup instead of being silently dropped. See CHANGELOG.md before upgrading.

What You Can Do

• "What's the status of PROJ-1234?"
• "Search for all open bugs assigned to me in the BACKEND project"
• "What fields do I need to create a Bug in PROJ?"
• "Create a story for the database migration under epic PROJ-100"
• "Log 2 hours against PROJ-1234 for the review"
• "Attach this screenshot to PROJ-1234"
• "Who changed the status of PROJ-1234, and when?"
• "What's in the active sprint on the Platform board?"

Why This Server

Quick Start

1. Create a scoped API token

1. Go to Atlassian API Tokens
2. Click "Create API token with scopes" — not plain "Create API token", which produces a classic token that will not work
3. Select app: Jira
4. The scope picker is a searchable box, not a list. Paste each scope string in and select the match.

A good starting set:

read:jira-work      write:jira-work      read:jira-user      read:me

That covers every default toolset. See Scopes for the opt-in toolsets.

Atlassian gives no way to read a token's scopes back after creation, and no way to edit them — changing scopes means minting a new token. Name your tokens descriptively; the name is the only record of what they can do.

2. Add to your AI client

Claude Desktop / Claude Code — add to .mcp.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "mcp-jira-scoped"],
      "env": {
        "JIRA_INSTANCE": "yourcompany",
        "JIRA_USER_EMAIL": "you@yourcompany.com",
        "JIRA_API_TOKEN": "<your-scoped-token>",
        "JIRA_SCOPES": "read:jira-work,write:jira-work"
      }
    }
  }
}

Cursor — the same config under Settings → MCP Servers.

VS Code (Copilot) — the same, in .vscode/mcp.json under servers.

Configuration

Shortened. The full README is on GitHub.