# JIRA MCP Server This is a Model Context Protocol (MCP) server that provides tools for interacting with JIRA. It allows you to fetch tickets from active sprints and get detailed ticket information through the MCP interface. ## Features The server provides the following tools: 1. `list-sprint-tickets`: Gets all tickets in the active sprint for a given project - Required parameter: `projectKey` (string) 2. `get-ticket-details`: Gets detailed information about a specific ticket - Required parameter: `issueKey` (string) 3. `add-comment`: Adds a comment to a specific ticket - Required parameter: `issueKey` (string) - Either `comment` (string) or `filePath` (string) — see [Editing content from a file](#editing-content-from-a-file) - Optional parameter: `commentFormat` — `plain` (default), `wiki`, `markdown` or `adf` 4. `link-issues`: Links every outward issue to every inward issue, read as "outward *blocks* inward" - Required parameters: `outwardIssueKeys`, `inwardIssueKeys` (string arrays) — with `linkType: "Blocks"`, the outward keys are the blockers - Optional parameter: `linkType` — the type's name (`Blocks`, or `3. Blocks` on sites that number them) or its inward/outward description; defaults to `Relates`. `unlink-issues` accepts the same values. - Results are reported in words, e.g. `PROJ-1 blocks PROJ-2` 5. `update-description`: Updates the description of a specific ticket - Required parameter: `issueKey` (string) - Either `description` (string) or `filePath` (string) — see [Editing content from a file](#editing-content-from-a-file) - Optional parameter: `descriptionFormat` — `plain` (default), `wiki`, `markdown` or `adf` 6. `list-child-issues`: Gets all child issues of a parent ticket - Required parameter: `parentKey` (string) 7. `create-sub-ticket`: Creates a sub-ticket (child issue) for a parent ticket - Required parameter: `parentKey` (string) - Required parameter: `summary` (string) - Optional parameter: `description` (string) or `filePath` (string) — see [Editing content from a file](#editing-content-from-a-file) - Optional parameter: `issueType` (string) - The name of the sub-task issue type (e.g., 'Sub-task') 8. `add-attachment`: Uploads local files as attachments to a ticket - Required parameter: `issueKey` (string) - Required parameter: `filePaths` (string array) — every path is checked before any upload, so a bad path uploads nothing 9. `notifications`: Reads your Atlassian notifications (the bell icon), newest first - Optional parameter: `since` / `until` — an ISO date/time (`2026-10-01`, `2026-10-01T09:00:00Z`) or a duration back from now (`30m`, `24h`, `7d`, `2w`) - Optional parameter: `limit` (number) — default 20, max 100 - Optional parameter: `unreadOnly` (boolean), `category` (`direct` or `watching`), `product` (e.g. `jira`, `confluence`) - Optional parameter: `ids` (string array) — return only these notifications (the `ID:` line of each result); the other filters and `limit` are ignored - Optional parameter: `markAsRead` (boolean, default `false`) — marks the returned unread notifications as read, so `ids` + `markAsRead` marks exactly those; grouped notifications are marked as a whole. The API has no way to delete or dismiss a notification. - Notifications come from the Atlassian GraphQL gateway (`/gateway/api/graphql`), which accepts the same API token. The feed is requested for the site in `JIRA_HOST` (its cloud ID is read from the public `/_edge/tenant_info`); without that routing the gateway returns only platform-wide admin notices. ## Setup 1. Install dependencies: ```bash npm install ``` 2. Build the TypeScript code: This step is only needed for Cline on Windows, which currently has an issue executing npx ```bash npm run build ``` 3. Configure the MCP settings in your Claude app settings file (usually located at `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json` on Windows): Settings for Claude: ```json { "mcpServers": { "jira": { "command": "npx", "args": ["path/to/this/repo/jira.ts"], "env": { "JIRA_HOST": "https://your-domain.atlassian.net", "JIRA_EMAIL": "your-email@example.com", "JIRA_API_TOKEN": "your-api-token" } } } } ``` Settings for Cline: ```json { "mcpServers": { "jira": { "command": "node", "args": ["path/to/this/repo/dist/jira.js"], "env": { "JIRA_HOST": "https://your-domain.atlassian.net", "JIRA_EMAIL": "your-email@example.com", "JIRA_API_TOKEN": "your-api-token" } } } } ``` ## Configuration You'll need to set up the following environment variables in your MCP settings: 1. `JIRA_HOST`: Your Atlassian domain URL (e.g., `https://your-company.atlassian.net`) 2. `JIRA_EMAIL`: Your JIRA account email 3. `JIRA_API_TOKEN`: Your JIRA API token - You can generate an API token from your [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens) ## Usage Once configured, you can use the tools through the MCP interface in Claude: ### List Sprint Tickets To get all tickets in the active sprint for a project: ```typescript jira list-sprint-tickets { "projectKey": "YOUR_PROJECT_KEY" } ``` ### Get Ticket Details To get detailed information about a specific ticket: ```typescript jira get-ticket-details { "issueKey": "PROJECT-123" } ``` ### Editing content from a file `update-description`, `update-comment`, `add-comment`, `create-ticket` and `create-sub-ticket` accept `filePath` instead of inline text. This is meant for long content: keep the source in a file, edit that file, and re-send — no need to repost the whole body through the tool call each time. On the two create tools the description stays optional, so omitting both is still fine. The format is inferred from the extension, so `descriptionFormat` / `commentFormat` can be omitted: | Extension | Format | Content | | -------------------- | ---------- | ---------------------------------------- | | `.md`, `.markdown` | `markdown` | Markdown (`## headings`, `**bold**`) | | `.wiki`, `.jira` | `wiki` | Jira wiki markup (`h2.`, `{code}`) | | `.json`, `.adf` | `adf` | Raw Atlassian Document Format JSON | | `.txt`, `.text` | `plain` | Plain text, wrapped in a paragraph | Passing the format explicitly overrides the extension, which is also how to use a file with any other extension. Paths are absolute or relative to the server's working directory. ```json { "issueKey": "PROJECT-123", "filePath": "/abs/path/to/description.md" } ``` An empty file is rejected rather than wiping the existing description or comment, and passing both the inline text and `filePath` is an error. Markdown constructs that end up empty — a table cell (header or body), a list item, a blockquote, a fenced code block — are repaired into valid ADF before sending. Jira's validator refuses an empty `tableHeader` / `tableCell` / `listItem` / `blockquote` with a bare `400 INVALID_INPUT` that names the *field* (`errors.comment`) and not the offending node, so without this repair the whole comment looks rejected while a single empty cell is at fault. ### Patching existing content To change part of a description or comment that already exists, export it first with `export-content`, edit the file, and re-upload it — no need to rewrite the whole thing: ```json { "issueKey": "PROJECT-123", "commentId": "54660", "filePath": "/tmp/pir-timeline.md" } ``` The export reports whether that content is safe to re-upload as markdown. Jira stores content as ADF, and constructs such as panels, mentions, status lozenges, media, tables, task lists and expands have no markdown equivalent — re-uploading markdown would silently drop them. When any are present the tool warns and lists them; export with `"format": "adf"` instead and patch the JSON, which always round-trips exactly (`.json` files are recognised as ADF on upload). Omit `filePath` to get the content back inline instead of writing a file. Comment IDs are shown by `get-ticket-details`. ### Content versions (optimistic concurrency) `update-description` and `update-comment` require `expectedVersion` whenever the content being replaced is not empty: the version the edit was based on. If the content changed in Jira since, the update is refused instead of silently discarding that change — the same lock Confluence gets from its page version numbers. Jira has no version number of its own, and an issue's `updated` timestamp is not a substitute: it moves for any change to the issue, so transitions, labels and new comments would all reject description patches that never conflicted. The version is therefore a hash of the content itself (`v1-…`), so it changes exactly when the thing being patched changes. Versions come from `export-content` and from `get-ticket-details`, which reports `Description version:` and a `version:` for every comment — so a small inline edit needs no export round-trip. **Writing a description for the first time needs no version.** Omitting `expectedVersion` is itself the assertion "there is nothing here yet", which the server checks: the write goes through when the description is still empty, and is refused — naming the version now in Jira — when someone wrote one meanwhile. So the lock covers the first write as well, without the caller having to fetch the version of empty content. Pass `"force": true` to skip the check and overwrite regardless. ### Embedding files in descriptions and comments `add-comment`, `update-comment`, `update-description`, `create-ticket` and `create-sub-ticket` embed files referenced with the image syntax of the content format: ```markdown ![the error dialog](./screenshots/error.png) ``` ``` !error.png! (wiki, image) [^report.pdf] (wiki, file) ``` Each reference resolves to an issue attachment. Jira stores a file shown in a comment as an issue attachment, so comments and descriptions work the same way. References resolve in this order: 1. `attachment:` embeds an attachment already on the ticket. 2. A local path (relative to the content file, or to the server's working directory for inline text) is uploaded. If the ticket already has an attachment with the same name and size, that attachment is reused, so re-sending an edited file does not attach the same screenshot again. 3. Otherwise, an attachment already on the ticket with that filename is used. Every reference is checked before anything is uploaded or written. A single bad reference makes the call fail with nothing changed. Web URLs (`https://…`) are left as they are. Images render inline, and other files appear as attachment links. When creating a ticket, the description is written in a second step after the issue exists, because files can only be attached to an existing issue. ## Development The server is written in TypeScript and uses: - `@modelcontextprotocol/sdk` for MCP server implementation - `jira.js` for JIRA API integration Recommended scripts: - Build once: `npm run build` - Build and watch: `npm run build:watch` - Type-check only: `npm run typecheck` - Dev run with watch: `npm run start:dev` - Run compiled server: `npm start` - Format check: `npm run fmt:check` - Format write: `npm run fmt` - Unit tests: `npm test` `npm test` runs unit tests only. They use fake Jira clients, need no credentials, and never touch a real Jira instance. Checks against a live Jira that create tickets, comments or attachments are run by hand as one-off scripts and are not committed. Neither kind of test should commit details of a real Jira instance, such as its hostname, project keys, issue keys, people's names or attachment IDs. Typical workflow: 1. Make changes to [`jira.ts`](jira.ts) 2. Run `npm run start:dev` during development, or `npm run build` then `npm start` for compiled run 3. Restart your MCP client if needed to pick up changes ## Error Handling The server includes error handling for: - Invalid JIRA credentials - Missing active sprints - Invalid project keys or issue keys - Network errors Error messages will be returned in the tool response.