# Jira MCP Server

> **Retired as of September 29, 2026.** This project no longer receives feature updates, bug fixes, or dependency and security maintenance. Existing code remains available under the MIT license. For new Jira Cloud integrations, use the official [Atlassian Rovo MCP Server](https://developer.atlassian.com/cloud/rovo-mcp/guides/getting-started/).

This local Model Context Protocol (MCP) server exposes Jira operations to MCP clients over stdio. Its implementation combines `jira-python` with direct Jira Cloud REST API v3 requests.

The API-token authentication gap this project originally addressed is now covered by Rovo. See the [migration guide](docs/rovo-migration.md) for authentication requirements, client setup, and workflow checks before switching.

## Compatibility

- Python 3.10 or higher.
- Jira Cloud with an Atlassian account email and API token using `basic_auth`.
- An MCP client that can launch a local stdio server.

The direct API client uses `/rest/api/3`. Jira Server and Data Center compatibility, including PAT-only authentication, has not been validated and is not supported by this retirement release. Earlier documentation claiming those configurations were supported was incorrect. Retained legacy authentication branches do not establish end-to-end compatibility.

## Available tools

| Tool | Purpose |
| --- | --- |
| `get_jira_projects` | List accessible Jira projects. |
| `get_jira_issue` | Get an issue by key. |
| `search_jira_issues` | Search issues using JQL. |
| `create_jira_issue` | Create one issue. |
| `create_jira_issues` | Create multiple issues through Jira's bulk API. |
| `add_jira_comment` | Add a comment to an issue. |
| `get_jira_transitions` | List available workflow transitions. |
| `transition_jira_issue` | Transition an issue to another status. |
| `create_jira_project` | Create a project, subject to Jira permissions. |
| `get_jira_project_issue_types` | List issue types available for a project. |

## Legacy installation

Use a checkout of this repository to obtain the final code and documentation. Previously published packages may predate the retirement fixes.

### From source with uv

Install [uv](https://github.com/astral-sh/uv), then:

```bash
git clone https://github.com/InfinitIQ-Tech/mcp-jira.git
cd mcp-jira
uv sync
```

### From source with pip

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install .
```

The historical package installation commands are `uv pip install mcp-server-jira` and `python -m pip install mcp-server-jira`.

## Legacy configuration

Set these environment variables for Jira Cloud:

```bash
export JIRA_SERVER_URL="https://your-domain.atlassian.net"
export JIRA_AUTH_METHOD="basic_auth"
export JIRA_USERNAME="your_email@example.com"
export JIRA_TOKEN="your_api_token"
```

`JIRA_USERNAME` is the Atlassian account email. `JIRA_TOKEN` is its Jira Cloud API token. `JIRA_PASSWORD` and `token_auth` remain in legacy code, but are not the recommended Jira Cloud configuration. Keep credentials out of version control.

The repository includes [.env.example](.env.example). To use a `.env` file with uv, pass it explicitly:

```bash
cp .env.example .env
# Edit .env with your Jira Cloud credentials.
uv run --env-file .env mcp-server-jira
```

With environment variables already set, run either:

```bash
uv run mcp-server-jira
```

or, after pip installation:

```bash
python -m mcp_server_jira
```

### Docker

The server uses stdio rather than an HTTP listener. Keep stdin open when launching it through an MCP client:

```bash
docker build -t mcp-jira .
docker run --rm -i --env-file .env mcp-jira
```

### Example local MCP client configuration

For clients that support the `mcpServers` command configuration, such as Claude Desktop, use absolute paths to uv and the repository checkout:

```json
{
  "mcpServers": {
    "jira": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-jira",
        "run",
        "mcp-server-jira"
      ],
      "env": {
        "JIRA_SERVER_URL": "https://your-domain.atlassian.net",
        "JIRA_AUTH_METHOD": "basic_auth",
        "JIRA_USERNAME": "your_email@example.com",
        "JIRA_TOKEN": "your_api_token"
      }
    }
  }
}
```

Client configuration locations and supported transports vary. This example describes the legacy local server, not a Rovo configuration or a claim that every client has been tested.

## Migration and maintenance

Follow [Migrating to Atlassian Rovo MCP](docs/rovo-migration.md) before removing the local connector. Rovo is an Atlassian-hosted service with different authentication, tool names, and response schemas. There is no automatic configuration migration.

Users who retain or fork this code are responsible for future maintenance and compatibility with Jira and MCP clients.

## License

MIT