MCP Jira Scoped

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, jira_search paginates on nextPageToken instead of startAt, and an unrecognised JIRA_SCOPES 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": " ", "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

Restricting to specific projects

JIRA_PROJECTS=PROJ,OPS

Any request naming a different project is refused before the API call, and every JQL search is wrapped so it cannot reach outside the list — an OR in the query can't escape it. This is a blast-radius control for agent use, not a replacement for Jira permissions: it constrains what the server will ask for, and can't widen what the token already allows.

Toolsets

44 tools is past the point where model tool-selection starts to degrade, and some clients silently truncate long tool lists. So tools are grouped, and only the common ones load by default.

JIRA_TOOLSETS=default              # the six default groups (34 tools) — this is the default

JIRA_TOOLSETS=default,agile # add boards and sprints JIRA_TOOLSETS=all # everything (44 tools) JIRA_TOOLSETS=core,users # a minimal surface

The choice is made once at startup. Disabled toolsets are named in the server's instructions, so the model knows they exist and can tell you how to enable them.

Available Tools (44)

core

users

attachments

links

worklogs

metadata

agile *(opt-in)*

versions *(opt-in)*

filters *(opt-in)*

labels *(opt-in)*

Content format

Every content tool takes a format parameter — markdown (default), text, or adf.

Markdown is preserved in both directions: headings, bold/italic/strike, inline code, links, bullet/ordered/task lists, fenced code blocks with language, blockquotes, tables, rules, panels and mentions. Verified against 300 real issue descriptions with zero content loss.

• markdown — full structure. What you want almost always.
• text — the pre-2.0 behaviour: literal, with URLs auto-linked and [label|url] wiki markup.
• adf — raw Atlassian Document Format JSON, in and out, for full programmatic fidelity.

Scopes

Most Jira platform endpoints accept either a classic scope or its granular equivalent — read:jira-work or read:issue:jira. This server accepts both.

Jira Software is the exception. It publishes no classic scopes at all, so the agile toolset needs granular ones and cannot be satisfied by read:jira-work. Note read:project:jira is required alongside the board scope; without it /rest/agile/1.0/board returns 401 in a way that looks like a different problem entirely.

You may find community answers claiming scoped API tokens cannot reach the Jira Software API at all. That is incorrect, and we verified it: a token carrying only read:board-scope:jira-software, read:sprint:jira-software, write:sprint:jira-software and read:project:jira reads boards and sprints and creates sprints successfully, while returning 401 on every platform endpoint. Details in docs/research/scoped-tokens-api-reach.md.

| core | read:jira-work, write:jira-work | read:issue:jira, write:issue:jira, `r