# jira-mcp

A self-hosted MCP server for **Jira Cloud**, built with [FastMCP](https://gofastmcp.com) in Python.

Tool names and signatures mirror the [official Atlassian Rovo MCP Server](https://github.com/atlassian/atlassian-mcp-server), so prompts and skills written for the official server work here too. One intentional difference: there is **no `cloudId` parameter** — this server is bound to a single Jira site via configuration.

## Tools

| Tool | Description |
| --- | --- |
| `atlassianUserInfo` | Info about the authenticated user |
| `getAccessibleAtlassianResources` | The connected Jira site |
| `lookupJiraAccountId` | Resolve a user's accountId by name/email |
| `getVisibleJiraProjects` | List/search visible projects |
| `getJiraProjectIssueTypesMetadata` | Issue types available in a project |
| `getJiraIssueTypeMetaWithFields` | Fields (incl. required/custom) for an issue type |
| `getJiraIssue` | Get one issue with description and comments |
| `searchJiraIssuesUsingJql` | JQL search with pagination |
| `getJiraIssueRemoteIssueLinks` | Remote (web) links on an issue |
| `createJiraIssue` | Create an issue (supports `additional_fields`) |
| `editJiraIssue` | Update issue fields |
| `addCommentToJiraIssue` | Comment on an issue |
| `getTransitionsForJiraIssue` | Available workflow transitions |
| `transitionJiraIssue` | Move an issue through a transition |

Descriptions and comments are accepted as **plain text** and converted to Atlassian Document Format automatically; ADF in responses is flattened back to plain text.

## Setup

1. Create an API token at <https://id.atlassian.com/manage-profile/security/api-tokens>
2. Copy the env template and fill it in:

   ```sh
   cp .env.example .env
   ```

## Run with Docker (recommended)

```sh
docker build -t jira-mcp .
```

### As a stdio server (Docker Desktop / MCP clients that spawn a container)

Add to your MCP client config (e.g. Claude Desktop / Claude Code):

```json
{
  "mcpServers": {
    "jira": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file", "/absolute/path/to/jira-mcp/.env", "jira-mcp"]
    }
  }
}
```

### As a long-running HTTP server

```sh
docker run --rm --env-file .env -e MCP_TRANSPORT=http -p 8000:8000 jira-mcp
```

Then point your MCP client at `http://localhost:8000/mcp`.

## Run locally (without Docker)

```sh
pip install -e .
jira-mcp
```

## Configuration

| Variable | Required | Description |
| --- | --- | --- |
| `JIRA_URL` | ✅ | Your site, e.g. `https://your-company.atlassian.net` |
| `JIRA_EMAIL` | ✅ | Email of the account the token belongs to |
| `JIRA_API_TOKEN` | ✅ | Atlassian API token |
| `JIRA_TIMEOUT` | — | HTTP timeout in seconds (default `30`) |
| `MCP_TRANSPORT` | — | `stdio` (default) or `http` |
| `MCP_HOST` / `MCP_PORT` | — | HTTP bind address (default `0.0.0.0:8000`) |