{
  "markdown": "# mcp-jira-scoped\n\n[![npm version](https://img.shields.io/npm/v/mcp-jira-scoped.svg)](https://www.npmjs.com/package/mcp-jira-scoped)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org)\n\n**The only MCP server for Jira that works with Atlassian's scoped API tokens.**\n\nEvery 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.\n\n## What You Can Do\n\nOnce connected, you can ask your AI assistant things like:\n\n- *\"What's the status of PROJ-1234?\"*\n- *\"Search for all open bugs assigned to me in the BACKEND project\"*\n- *\"Create a story in PROJ for the database migration, priority P2, under epic PROJ-100\"*\n- *\"Move PROJ-1234 to In Progress\"*\n- *\"Add a comment to PROJ-1234 saying the fix is deployed to staging\"*\n- *\"Link PROJ-1234 as blocking PROJ-5678\"*\n- *\"Find all issues with 'auth' in the summary updated this week\"*\n\n## Why This Server\n\n| | mcp-jira-scoped | Other Jira MCP servers |\n|---|---|---|\n| **Token type** | Scoped (modern, `ATATT` prefix) | Classic (being deprecated) |\n| **Auth gateway** | `api.atlassian.com` | `yoursite.atlassian.net` |\n| **Scope enforcement** | Server-side, before every API call | None — relies on AI self-restraint |\n| **Default mode** | Read-only (write must be explicitly granted) | Full access |\n| **Delete safety** | Requires `confirm: true` parameter | No guard |\n\n## Quick Start\n\n### 1. Create a Scoped API Token\n\n1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)\n2. Click **\"Create API token with scopes\"**\n3. Grant the scopes you need:\n   - `read:jira-work` — read issues, search, comments, projects\n   - `write:jira-work` — create/update/delete issues, add comments\n   - `read:jira-user` — look up users\n   - `read:me` — read your own profile\n\n### 2. Add to Your AI Client\n\n#### Claude Desktop / Claude Code\n\nAdd to your `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-jira-scoped\"],\n      \"env\": {\n        \"JIRA_INSTANCE\": \"yourcompany\",\n        \"JIRA_USER_EMAIL\": \"you@yourcompany.com\",\n        \"JIRA_API_TOKEN\": \"<your-scoped-token>\",\n        \"JIRA_SCOPES\": \"read:jira-work,write:jira-work\"\n      }\n    }\n  }\n}\n```\n\n#### Cursor\n\nAdd the same config to Cursor's MCP settings (Settings > MCP Servers).\n\n#### VS Code (Copilot)\n\nAdd to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-jira-scoped\"],\n      \"env\": {\n        \"JIRA_INSTANCE\": \"yourcompany\",\n        \"JIRA_USER_EMAIL\": \"you@yourcompany.com\",\n        \"JIRA_API_TOKEN\": \"<your-scoped-token>\",\n        \"JIRA_SCOPES\": \"read:jira-work,write:jira-work\"\n      }\n    }\n  }\n}\n```\n\n## Configuration\n\n| Env Var | Required | Description |\n|---------|----------|-------------|\n| `JIRA_INSTANCE` | Yes | Instance name (e.g. `mycompany` for `mycompany.atlassian.net`) |\n| `JIRA_API_TOKEN` | Yes | Scoped API token (`ATATT...` prefix) |\n| `JIRA_USER_EMAIL` | Yes | Email associated with the token |\n| `JIRA_SCOPES` | No | Comma-separated scopes. Defaults to `read:jira-work` (read-only) |\n| `JIRA_CLOUD_ID` | No | Atlassian Cloud ID. Auto-fetched if not set. Find it at `https://yoursite.atlassian.net/_edge/tenant_info` |\n\n## Available Tools (14)\n\n### Read Tools (`read:jira-work`)\n\n| Tool | Description |\n|------|-------------|\n| `jira_get_issue` | Get issue by key. Pass `includeCustomFields: true` to return all custom fields |\n| `jira_search` | Search issues via JQL with pagination |\n| `jira_list_comments` | List comments on an issue |\n| `jira_list_projects` | List accessible projects |\n| `jira_get_project` | Get project details by key |\n| `jira_list_link_types` | List available issue link types |\n| `jira_list_fields` | List all fields (system + custom) — discover `customfield_*` IDs |\n| `jira_list_attachments` | List attachments on an issue with filename, size, MIME type, and download URL |\n| `jira_get_transitions` | Get available transitions for an issue with required screen fields expanded |\n\n### Write Tools (`write:jira-work`)\n\n| Tool | Description |\n|------|-------------|\n| `jira_create_issue` | Create an issue (task, bug, story, epic). Supports custom fields |\n| `jira_update_issue` | Update fields on an issue. Supports custom fields |\n| `jira_add_comment` | Add a comment (plain text auto-converted to ADF) |\n| `jira_transition_issue` | Move an issue to a new status. Accepts `fields` and `comment` for transition screens |\n| `jira_delete_issue` | Delete an issue (requires `confirm: true` safety guard) |\n| `jira_link_issues` | Link two issues (blocks, relates, split, clone, etc.) |\n| `jira_add_attachment` | Upload a local file as an attachment to an issue |\n| `jira_delete_attachment` | Delete an attachment by ID (requires `confirm: true` safety guard) |\n\n### User Tools (`read:jira-user`)\n\n| Tool | Description |\n|------|-------------|\n| `jira_get_user` | Get user info by account ID |\n| `jira_search_users` | Search users by name or email |\n\n## Safety\n\n1. **Scope enforcement** — tools are blocked server-side if their required scope isn't granted. The API call never happens.\n2. **Read-only default** — if `JIRA_SCOPES` is not set, only read tools are even registered.\n3. **Delete confirmation** — `jira_delete_issue` requires `confirm: true`.\n4. **No token logging** — tokens are redacted from all error messages via `sanitizeError`.\n5. **No admin operations** — no project creation/deletion, workflow changes, or webhook management. Ever.\n\n## Troubleshooting\n\n### \"Client must be authenticated\" (401)\n\nYou'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.\n\n### \"Failed to parse Connect Session Auth Token\" (403)\n\nYou'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.\n\n### Token scopes vs server scopes\n\nThere are two layers of scope enforcement:\n\n1. **Atlassian's scopes** — set when you create the token. These control what Atlassian's API allows.\n2. **Server scopes** (`JIRA_SCOPES` env var) — control what tools this MCP server makes available. These can only be *more* restrictive, never less.\n\nIf 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.\n\n### Custom fields\n\nJira 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`:\n\n```\nCreate an issue in PROJ with summary \"Fix login bug\" and set customfield_10016 to 3\n```\n\nThe AI will pass `{\"customFields\": {\"customfield_10016\": 3}}`. To find custom field IDs, check your Jira project's field configuration.\n\n### Cloud ID\n\nThe 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.\n\n## Roadmap\n\nSee [Prioritised-TodoList.md](Prioritised-TodoList.md) for the full feature checklist — what's built, what's next, and where contributions are welcome. Key areas open for contribution:\n\n- **Issue tools** — assign shortcut, create/transition metadata discovery\n- **Comments** — edit and delete\n- **Watchers & Worklogs** — full CRUD\n- **Boards & Sprints** — Agile workflow support\n- **Attachments** — list, download, upload\n\n## Development\n\n```bash\ngit clone https://github.com/deepwired/mcp-jira.git\ncd mcp-jira\nnpm install\nnpm run build\nnpm test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details on adding tools and submitting PRs.\n\n## Note on Package Naming\n\nThe 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.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n",
  "bytes": 8499,
  "sha": "9d6630c30f15f0ca0d158ba9b486a19017c977669e1fb8b4a7751e5a4acc28b5",
  "repo_slug": "deepwired/mcp-jira",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_deepwired_mcp_jira_scoped_06c74a72/readme"
}