io.github.deepwired/mcp-jira-scoped
Jira MCP server with scoped API tokens via api.atlassian.com gateway
Open source Open in the app JSON README (API)
About
Jira MCP server with scoped API tokens via api.atlassian.com gateway
Details
- Kind
- MCP servers
- Topic
- Productivity
- Publisher
- deepwired
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.0
- Stars
- 3
- Forks
- 2
- Last push
- 2026-04-01T02:20:03Z
- Repository state
- ativo
- Language
- TypeScript
- License
- Apache-2.0
- Added
- 2026-08-29 03:02:41
- Updated
- 2026-08-29 03:02:41
- Origin id
io.github.deepwired/mcp-jira-scoped
README
# mcp-jira-scoped
[](https://www.npmjs.com/package/mcp-jira-scoped)
[](LICENSE)
[](https://nodejs.org)
[](https://www.typescriptlang.org)
**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
1. Go to [Atlassian API Tokens](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click **"Create API token with scopes"**
3. 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
1. **Scope enforcement** — tools are blocked server-side if their required scope isn't granted. The API call never happens.
2. **Read-only default** — if `JIRA_SCOPES` is not set, only read tools are even registered.
3. **Delete confirmation** — `jira_delete_issue` requires `confirm: true`.
4. **No token logging** — tokens are redacted from all error messages via `sanitizeError`.
5. **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:
1. **Atlassian's scopes** — set when you create the token. These control what Atlassian's API allows.
2. **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`:
```
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](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](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](LICENSE).