# jira-mcp

An [MCP](https://modelcontextprotocol.io) server that connects **Claude Code** (or any MCP client) to **Jira Cloud**, so an AI agent can find a ticket, work on it, and report back on the ticket in one flow.

> "Find my open bugs in PROJ, fix PROJ-12, then comment on the ticket with what changed."

## Tools

| Tool | What it does |
|------|--------------|
| `search_issues` | Search issues with JQL (uses the current `/rest/api/3/search/jql` endpoint) |
| `get_issue` | Read one issue: summary, status, description and the latest comments |
| `create_issue` | Create a Task, Bug or Story, with an optional description |
| `add_comment` | Comment on an issue, e.g. a summary of a fix |

Descriptions and comments are converted to and from Atlassian Document Format (ADF), which Jira Cloud v3 requires for rich text. Errors such as a bad token (401) or an unknown key (404) come back to the agent as readable tool errors instead of crashing the server.

## Setup

1. Create a Jira API token: Atlassian account → Security → **API tokens**.
2. Build the server:

   ```bash
   npm install
   npm run build
   ```

3. Register it with Claude Code:

   ```bash
   claude mcp add jira \
     -e JIRA_BASE_URL=https://your-site.atlassian.net \
     -e JIRA_EMAIL=you@example.com \
     -e JIRA_API_TOKEN=your-api-token \
     -- node /absolute/path/to/jira-mcp/dist/index.js
   ```

4. Start `claude` and ask: *"Search open issues in project PROJ."*

Never commit your token. `.env` is git-ignored; see `.env.example` for the variables.

## Stack

TypeScript, the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk), Zod for tool input schemas, and the Jira Cloud REST API v3 over stdio transport.

## License

MIT