Jira MCP Server

A Model Context Protocol (MCP) server for Jira Cloud. It exposes issue, project, board, sprint, search, comment, worklog, link, version, attachment and property operations as MCP tools, backed directly by the Jira Cloud REST API (v3) and Agile API (1.0).

This project is not affiliated with, endorsed by, or sponsored by Atlassian.

Overview

Auth: Jira Cloud API token (email + token, Basic Auth) — no OAuth redirect flow needed.
HTTP client: Node's native fetch/FormData — no extra HTTP dependency.
Runtime deps: just @modelcontextprotocol/sdk and zod.
Destructive/admin tools are off by default: deleteJiraIssue, deleteJiraComment, deleteJiraIssueAttachment, createJiraProject, updateJiraProject only register when you explicitly opt in via env vars (see below).

Prerequisites

Node.js v20 or higher (native fetch/FormData need to be stable).
A Jira Cloud site and an API token — create one at https://id.atlassian.com/manage-profile/security/api-tokens.
An MCP-compatible client (VS Code + GitHub Copilot, Claude Code, etc.).

Setup

Clone/copy this project, then install dependencies:
```
npm install
npm run build
```
Or, once published, install as a dependency of your own project:

npm i @automate-io/jira-mcp-server@latest


## Configuration

The server reads its Jira connection from environment variables — set these in your MCP
client's server config, never commit them to source control.

| Variable | Required | Description |
| --- | --- | --- |
| `JIRA_URL` | Yes | Your site, e.g. `https://your-domain.atlassian.net` |
| `JIRA_USERNAME` | Yes | Account email used to generate the API token |
| `JIRA_TOKEN` | Yes | API token from id.atlassian.com |
| `JIRA_ENABLE_DELETE` | No | Set to `true` to register `deleteJiraIssue`/`deleteJiraComment`/`deleteJiraIssueAttachment` |
| `JIRA_ENABLE_MANAGE` | No | Set to `true` to register `createJiraProject`/`updateJiraProject` |

Example `.vscode/mcp.json` (also included in this repo, using prompted inputs so the token
isn't hardcoded):

```json
{
  "servers": {
 "jira-mcp": {
   "type": "stdio",
   "command": "node",
   "args": ["node_modules/@automate-io/jira-mcp-server/dist/server.js"],
   "cwd": "${workspaceFolder}",
   "env": {
     "JIRA_URL": "${input:jiraBaseUrl}",
     "JIRA_USERNAME": "${input:jiraEmail}",
     "JIRA_TOKEN": "${input:jiraApiToken}"
   }
 }
  },
  "inputs": [
 { "id": "jiraBaseUrl", "type": "promptString", "description": "Jira Cloud site URL" },
 { "id": "jiraEmail", "type": "promptString", "description": "Jira account email" },
 { "id": "jiraApiToken", "type": "promptString", "description": "Jira API token", "password": true }
  ]
}

Tool catalogue

Grouped by file under src/tools/. 41 tools by default, 46 with delete/manage enabled.

File	Tools
`issues.ts`	getJiraIssue, createJiraIssue, editJiraIssue, listJiraIssueTransitions, transitionJiraIssue, listJiraIssueChangelogs, watchJiraIssue, deleteJiraIssue
`comments.ts`	listJiraIssueComments, addOrEditJiraIssueComment, deleteJiraComment
`worklogs.ts`	listJiraIssueWorklogs, addOrEditJiraIssueWorklog
`links.ts`	listJiraIssueLinkTypes, createJiraIssueLink, listJiraIssueRemoteIssueLinks
`search.ts`	searchJiraIssuesUsingJql
`users.ts`	getJiraCurrentUser, getJiraUser, lookupJiraAccountId, findJiraIssueAssignableUsers
`projects.ts`	listJiraProjects, listJiraProjectIssueTypesMetadata, getJiraIssueTypeMetaWithFields, listJiraStatuses, listJiraProjectComponents, createJiraProject, updateJiraProject
`versions.ts`	getJiraProjectVersions, manageJiraProjectVersion, getJiraProjectVersionRelatedWork, manageJiraProjectVersionRelatedWork
`boards.ts`	listJiraBoards, getJiraBoardConfig, getJiraBoardIssueData, createJiraBoard
`sprints.ts`	listJiraBoardSprints, getJiraBoardSprintData, manageJiraSprint
`filtersAndDashboards.ts`	listJiraFilters, listJiraDashboards
`properties.ts`	getJiraEntityProperty, editJiraEntityProperty
`attachments.ts`	uploadAttachmentToJiraIssue, downloadJiraIssueAttachment, deleteJiraIssueAttachment

Italicised tools require the matching JIRA_ENABLE_* flag.

Design notes

src/utilities/jira-client.ts is the single HTTP entry point (jiraRequest). It preserves the real HTTP status code on every response (including errors), parses the body by content-type instead of assuming JSON, and needs no manual context disposal since it's built on native fetch.
src/utilities/tool-helpers.ts provides safeHandler (shared try/catch) and toToolResult (maps a Jira response to MCP content with isError reflecting the real status), so each tool handler stays a few lines of Jira-specific logic instead of repeating boilerplate.
src/utilities/adf.ts converts plain text into the minimal Atlassian Document Format Jira Cloud's v3 API requires for rich-text fields (comments, descriptions, worklog comments).
searchJiraIssuesUsingJql uses the current token-paginated /rest/api/3/search/jql endpoint, since the older startAt-based /rest/api/3/search is deprecated.
Startup logs go to stderr, never stdout — stdout is reserved for the MCP JSON-RPC stream over the stdio transport, so anything else written there would corrupt it.

Troubleshooting

Server exits immediately with "Missing required environment variable": set JIRA_URL, JIRA_USERNAME, JIRA_TOKEN in your MCP client's server config.
401/403 from Jira: regenerate your API token, and confirm JIRA_USERNAME matches the Atlassian account that owns the token.
A delete/manage tool doesn't show up: set JIRA_ENABLE_DELETE / JIRA_ENABLE_MANAGE to "true" in the server's env config.