io.github.deepwired/mcp-jira-scoped

Official

by deepwired · TypeScript

Jira MCP server with scoped API tokens via api.atlassian.com gateway

Jira integration with scoped API tokens via Atlassian gateway.

Topics

aiai-integrationanthropicatlassianclaudeissue-trackingjirallmmcpmcp-servermodel-context-protocolproject-managementtypescriptscoped-tokens

README.md8 KBView on GitHub

mcp-jira-scoped

The only MCP server for Jira that works with Atlassian's scoped API tokens.

Every other Jira MCP server uses classic (unscoped) API tokens with basic auth against yoursite.atlassian.net. Atlassian is deprecating those. This server uses scoped tokens with the modern api.atlassian.com gateway — the way Atlassian intends these tokens to be used.

What You Can Do

Once connected, you can ask your AI assistant things like:

"What's the status of PROJ-1234?"
"Search for all open bugs assigned to me in the BACKEND project"
"Create a story in PROJ for the database migration, priority P2, under epic PROJ-100"
"Move PROJ-1234 to In Progress"
"Add a comment to PROJ-1234 saying the fix is deployed to staging"
"Link PROJ-1234 as blocking PROJ-5678"
"Find all issues with 'auth' in the summary updated this week"

Why This Server

	mcp-jira-scoped	Other Jira MCP servers
Token type	Scoped (modern, `ATATT` prefix)	Classic (being deprecated)
Auth gateway	`api.atlassian.com`	`yoursite.atlassian.net`
Scope enforcement	Server-side, before every API call	None — relies on AI self-restraint
Default mode	Read-only (write must be explicitly granted)	Full access
Delete safety	Requires `confirm: true` parameter	No guard

Quick Start

1. Create a Scoped API Token

Go to Atlassian API Tokens
Click "Create API token with scopes"
Grant the scopes you need:
- read:jira-work — read issues, search, comments, projects
- write:jira-work — create/update/delete issues, add comments
- read:jira-user — look up users
- read:me — read your own profile

2. Add to Your AI Client

Claude Desktop / Claude Code

Add to your .mcp.json:

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

Add the same config to Cursor's MCP settings (Settings > MCP Servers).

VS Code (Copilot)

Add to .vscode/mcp.json:

json

{
  "servers": {
    "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"
      }
    }
  }
}

Configuration

Env Var	Required	Description
`JIRA_INSTANCE`	Yes	Instance name (e.g. `mycompany` for `mycompany.atlassian.net`)
`JIRA_API_TOKEN`	Yes	Scoped API token (`ATATT...` prefix)
`JIRA_USER_EMAIL`	Yes	Email associated with the token
`JIRA_SCOPES`	No	Comma-separated scopes. Defaults to `read:jira-work` (read-only)
`JIRA_CLOUD_ID`	No	Atlassian Cloud ID. Auto-fetched if not set. Find it at `https://yoursite.atlassian.net/_edge/tenant_info`

Available Tools (14)

Read Tools (`read:jira-work`)

Tool	Description
`jira_get_issue`	Get issue by key. Pass `includeCustomFields: true` to return all custom fields
`jira_search`	Search issues via JQL with pagination
`jira_list_comments`	List comments on an issue
`jira_list_projects`	List accessible projects
`jira_get_project`	Get project details by key
`jira_list_link_types`	List available issue link types
`jira_list_fields`	List all fields (system + custom) — discover `customfield_*` IDs
`jira_list_attachments`	List attachments on an issue with filename, size, MIME type, and download URL
`jira_get_transitions`	Get available transitions for an issue with required screen fields expanded

Write Tools (`write:jira-work`)

Tool	Description
`jira_create_issue`	Create an issue (task, bug, story, epic). Supports custom fields
`jira_update_issue`	Update fields on an issue. Supports custom fields
`jira_add_comment`	Add a comment (plain text auto-converted to ADF)
`jira_transition_issue`	Move an issue to a new status. Accepts `fields` and `comment` for transition screens
`jira_delete_issue`	Delete an issue (requires `confirm: true` safety guard)
`jira_link_issues`	Link two issues (blocks, relates, split, clone, etc.)
`jira_add_attachment`	Upload a local file as an attachment to an issue
`jira_delete_attachment`	Delete an attachment by ID (requires `confirm: true` safety guard)

User Tools (`read:jira-user`)

Tool	Description
`jira_get_user`	Get user info by account ID
`jira_search_users`	Search users by name or email

Safety

Scope enforcement — tools are blocked server-side if their required scope isn't granted. The API call never happens.
Read-only default — if JIRA_SCOPES is not set, only read tools are even registered.
Delete confirmation — jira_delete_issue requires confirm: true.
No token logging — tokens are redacted from all error messages via sanitizeError.
No admin operations — no project creation/deletion, workflow changes, or webhook management. Ever.

Troubleshooting

"Client must be authenticated" (401)

You're probably using a scoped token against the old yoursite.atlassian.net URL. Scoped tokens (ATATT... prefix) only work via api.atlassian.com. This server handles this automatically — make sure you're using mcp-jira-scoped, not another Jira MCP server.

"Failed to parse Connect Session Auth Token" (403)

You're sending a scoped token as a Bearer token. Scoped tokens use Basic auth (email:token) via the api.atlassian.com gateway. Again, this server handles it — this error means you're using a different server.

Token scopes vs server scopes

There are two layers of scope enforcement:

Atlassian's scopes — set when you create the token. These control what Atlassian's API allows.
Server scopes (JIRA_SCOPES env var) — control what tools this MCP server makes available. These can only be more restrictive, never less.

If you get a 403 from Atlassian, check that your token has the required scope. If you get a scope enforcement error from the MCP server, check your JIRA_SCOPES env var.

Custom fields

Jira projects often have required custom fields (e.g. "Work Category", "Story Point Estimate"). Use the customFields parameter on jira_create_issue and jira_update_issue:

code

Create an issue in PROJ with summary "Fix login bug" and set customfield_10016 to 3

The AI will pass {"customFields": {"customfield_10016": 3}}. To find custom field IDs, check your Jira project's field configuration.

Cloud ID

The server auto-fetches your Cloud ID from https://yourinstance.atlassian.net/_edge/tenant_info. If this fails (e.g. corporate firewall), set JIRA_CLOUD_ID manually.

Roadmap

See Prioritised-TodoList.md for the full feature checklist — what's built, what's next, and where contributions are welcome. Key areas open for contribution:

Issue tools — assign shortcut, create/transition metadata discovery
Comments — edit and delete
Watchers & Worklogs — full CRUD
Boards & Sprints — Agile workflow support
Attachments — list, download, upload

Development

bash

git clone https://github.com/deepwired/mcp-jira.git
cd mcp-jira
npm install
npm run build
npm test

See CONTRIBUTING.md for details on adding tools and submitting PRs.

Note on Package Naming

The GitHub repo is mcp-jira but the npm package is mcp-jira-scoped. We plan to unify under mcp-jira in a future release. For now, use npx -y mcp-jira-scoped to run the server.

License

Apache 2.0 — see LICENSE.

Install

Configuration

Environment variables

JIRA_INSTANCErequired

Jira instance name (e.g. 'mycompany' for mycompany.atlassian.net)

JIRA_USER_EMAILrequired

Email associated with the API token

JIRA_API_TOKENrequiredsecret

Scoped API token from https://id.atlassian.com/manage-profile/security/api-tokens

JIRA_SCOPES

Comma-separated scopes: read:jira-work, write:jira-work, read:jira-user, read:me. Defaults to read:jira-work

JIRA_CLOUD_ID

Atlassian Cloud ID (auto-fetched if not set). Find at https://yoursite.atlassian.net/_edge/tenant_info

claude_desktop_config.json

{
  "mcpServers": {
    "mcp-jira-scoped": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-jira-scoped@1.0.0"
      ],
      "env": {
        "JIRA_INSTANCE": "<YOUR_JIRA_INSTANCE>",
        "JIRA_USER_EMAIL": "<YOUR_JIRA_USER_EMAIL>",
        "JIRA_API_TOKEN": "<YOUR_JIRA_API_TOKEN>",
        "JIRA_SCOPES": "<YOUR_JIRA_SCOPES>",
        "JIRA_CLOUD_ID": "<YOUR_JIRA_CLOUD_ID>"
      }
    }
  }
}

Topics

mcp-jira-scoped

What You Can Do

Why This Server

Quick Start

1. Create a Scoped API Token

2. Add to Your AI Client

Claude Desktop / Claude Code

Cursor

VS Code (Copilot)

Configuration

Available Tools (14)

Read Tools (read:jira-work)

Write Tools (write:jira-work)

User Tools (read:jira-user)

Safety

Troubleshooting

"Client must be authenticated" (401)

"Failed to parse Connect Session Auth Token" (403)

Token scopes vs server scopes

Custom fields

Cloud ID

Roadmap

Development

Note on Package Naming

License

Install

Configuration

Read Tools (`read:jira-work`)

Write Tools (`write:jira-work`)

User Tools (`read:jira-user`)