Jira MCP Server

A comprehensive MCP (Model Context Protocol) server for Jira Cloud integration, built with FastMCP v4. Provides 8 focused tools for complete Jira issue and project management, with automatic ADF formatting, multi-tenant HTTP support, and optional webhook MCP Events.

Version 4.1.0 — FastMCP v4 with opt-in MCP Events, encrypted persistent subscriptions, and signed Jira event delivery.

Breaking change in 4.0.0: the CLI's console script is renamed jira-cli → jira-mcp-cli, with no alias kept. If you're upgrading from 3.4.x, update any script, alias, or MCP client config that invokes jira-cli. The rename matches the jira-mcp-server / jira-mcp-http family and avoids clashing with the unrelated, better-known jira-cli project (binary jira), which this package's old name was easily confused with in docs and search.

Features

• 8 Focused Tools for complete Jira issue and project management
• MCP Events — monitor issue creation, issue updates, and new comments through signed webhooks, filtered by project or issue
• Interactive Elicitation — issue_create and issue_delete interactively request missing or confirmatory input
• Streamable-HTTP + Stdio Transport — run as an HTTP server or stdio for Claude Desktop
• Multi-Tenant HTTP — different clients can connect with different Jira credentials per request
• Smart Field Normalization — case-insensitive types/priorities, display-name assignee resolution, component name-to-ID lookup
• Automatic ADF Formatting — plain text and Markdown auto-converted to Atlassian Document Format
• Transition Resolution — use transition names ("In Progress") instead of numeric IDs
• JQL Search with verbosity control (ids / summary / full), token-based pagination, and an optional approximate match count
• Jira Cloud API v3 compatibility
• Docker Support with hot-reload development mode, loopback-bound by default
• Generated CLI (jira-mcp-cli) — drives the same 8 tools in-process for agents and scripts, no MCP client required
• Tests — unit, FastMCP Client, HTTP, and MCP Events lifecycle tests

Installation

Prerequisites

• Python 3.11+ (3.10 is not supported: the marklassian dependency imports typing.Required, which is 3.11+, despite declaring 3.10 support)
• Jira Cloud account with an API token (create one here)

Install from PyPI (Recommended)

The package is published to PyPI. Choose any Python package manager:

uvx (Run Without Installing)

The fastest way to try it — runs in an ephemeral environment with no permanent install:

uvx atlassian-jira-mcp-server

uv tool (Persistent Install)

Installs the CLI commands (jira-mcp-server, jira-mcp-http) in an isolated environment:

uv tool install atlassian-jira-mcp-server

pipx (Isolated Install)

Same concept as uv tool but using pipx:

pipx install atlassian-jira-mcp-server

pip (Virtual Environment)

pip install atlassian-jira-mcp-server

After any of the above, two CLI commands are available:

Command	Transport	Use Case
jira-mcp-server	stdio	Claude Desktop, Claude Code (stdio), any MCP client
jira-mcp-http	streamable-http	Multi-tenant HTTP deployment, remote access

MCP Client Configuration

Claude Desktop (stdio via PyPI)

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server",
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@domain.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  }
}

Claude Desktop (stdio via uvx — no install needed)

{
  "mcpServers": {
    "jira": {
      "command": "uvx",
      "args": ["atlassian-jira-mcp-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@domain.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  }
}

Claude Code (stdio)

claude mcp add jira -- jira-mcp-server

Or with uvx (no install):

claude mcp add jira -- uvx atlassian-jira-mcp-server

Then set environment variables in your shell or .env file.

Claude Code / Any HTTP Client

Start the HTTP server first:

jira-mcp-http
# or: uvx --from atlassian-jira-mcp-server jira-mcp-http

Then configure the client:

{
  "mcpServers": {
    "jira": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-Jira-Base-Url": "https://your-domain.atlassian.net",
        "X-Jira-Username": "your-email@domain.com",
        "X-Jira-Api-Token": "your-api-token"
      }
    }
  }
}

Install from Source (Development)

git clone https://github.com/your-username/atlassian-jira-mcp-server
cd atlassian-jira-mcp-server

python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

Or install directly as a uv tool from source:

git clone https://github.com/your-username/atlassian-jira-mcp-server
cd atlassian-jira-mcp-server
uv tool install . --force --reinstall

Docker (HTTP Transport)

git clone https://github.com/your-username/atlassian-jira-mcp-server
cd atlassian-jira-mcp-server

# Create a .env file with your credentials (see Configuration section)
cp .env.example .env  # edit with your values

# Build and start the server
docker-compose up -d

The server will be available at http://localhost:8000/mcp, bound to loopback only — docker-compose.yml publishes the port as 127.0.0.1:${MCP_PORT}:${MCP_PORT} by default, so nothing outside the host can reach it even without MCP_AUTH_TOKEN set.

To serve other machines, first set MCP_AUTH_TOKEN (and ideally REQUIRE_CLIENT_CREDENTIALS, see Security), then change the port mapping in docker-compose.yml to "${MCP_PORT:-8000}:${MCP_PORT:-8000}".

For multi-tenant mode, leave Jira credentials out of .env and provide them via headers or query params on each request instead.

Configuration

Environment Variables

Create a .env file in the project root:

# Jira credentials (required for single-tenant / env-based config)
JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your-email@domain.com
JIRA_API_TOKEN=your-api-token
JIRA_DEFAULT_PROJECT=PROJ          # Optional default project key

# HTTP server settings (HTTP transport only)
FASTMCP_HOST=0.0.0.0               # Default: 0.0.0.0
FASTMCP_PORT=8000                  # Default: 8000

# Optional bearer-token authentication for the MCP endpoint (HTTP transport
# only — ignored on stdio and in-process transports, which can't present a
# bearer header)
MCP_AUTH_TOKEN=your-secure-bearer-token

# Optional: reject HTTP requests that don't supply their own Jira credentials
# instead of falling back to the ones above (HTTP transport only — see
# Security below)
REQUIRE_CLIENT_CREDENTIALS=true

Multi-Source Credential Resolution (HTTP Transport)

For HTTP deployments, credentials are resolved per request using the following priority (highest to lowest):

1. Query parameters — ?jira_base_url=...&jira_username=...&jira_api_token=...
2. Authorization: Basic header — standard HTTP Basic Auth (username:api_token base64-encoded). Carries no base_url, so it never satisfies credential resolution on its own — pair it with a jira_base_url query param or an X-Jira-Base-Url header, or let base_url fall through to the environment
3. X-Jira-* headers — X-Jira-Base-Url, X-Jira-Username, X-Jira-Api-Token, X-Jira-Default-Project
4. Environment variables — fallback for single-tenant / Docker deployments

This allows a single HTTP server instance to serve multiple Jira tenants simultaneously.

When MCP_AUTH_TOKEN is set, MCP-level bearer auth consumes the Authorization header, so the Authorization: Basic credential tier above is unavailable — a request sending Basic credentials is rejected before tenant resolution runs. Use query parameters or X-Jira-* headers for per-tenant credentials in that configuration; both work fine alongside a Bearer token.

Example: Query Parameter Auth

curl "http://localhost:8000/mcp?jira_base_url=https://your-domain.atlassian.net&jira_username=user@example.com&jira_api_token=your-token"

Example: Basic Auth Header

curl -H "Authorization: Basic $(echo -n 'user@example.com:api-token' | base64)" \
     http://localhost:8000/mcp

Example: X-Jira-* Headers

curl -H "X-Jira-Base-Url: https://your-domain.atlassian.net" \
     -H "X-Jira-Username: your-email@domain.com" \
     -H "X-Jira-Api-Token: your-api-token" \
     http://localhost:8000/mcp

Security

• Environment credentials are a fallback, not a default for everyone. On the HTTP transport, any request that doesn't supply its own Jira credentials runs as whoever .env (or the shell environment) configures.
• MCP_AUTH_TOKEN is effectively mandatory for any deployment reachable by anything but you. It's off by default. Without it, and without per-request credentials, the server is an unauthenticated read/write/delete proxy to the operator's Jira account for anyone who can reach the port. Enabling it takes the Authorization: Basic credential tier out of play — see the note under Multi-Source Credential Resolution — so per-tenant credentials on a token-protected deployment need to travel as query parameters or X-Jira-* headers instead.
• REQUIRE_CLIENT_CREDENTIALS closes the fallback itself: set it to reject any HTTP request that doesn't carry its own Jira credentials, rather than silently running as the operator. Use it for multi-tenant deployments where every caller must bring their own auth. Checked per-field — supplying two of three credentials and letting the third come from env is still rejected. Has no effect on stdio or in-process transports, where env vars are the only mechanism. The rejection itself is a generic protocol error (Invalid request parameters) on the wire — FastMCP collapses the detailed PermanentError message before it reaches the client. The specific missing-field reason is written to the server log, not the response, so debugging a rejection means checking the log.
• The default docker-compose.yml binds the published port to 127.0.0.1, so a fresh Docker deployment isn't reachable from other machines even before you set anything. See Docker (HTTP Transport) for what to change to serve other machines.

Usage

Running the Server

HTTP Transport

# With Docker (recommended)
docker-compose up -d

# Manually via Python entry point
python -c "from server import run_http; run_http()"

# Or via the installed CLI command
jira-mcp-http

Stdio Transport (Claude Desktop)

# Via installed CLI command
jira-mcp-server

# Or directly
python server.py

Connecting with MCP Clients

See the MCP Client Configuration section under Installation above for Claude Desktop, Claude Code, and HTTP client setup.

For multi-tenant HTTP deployments, configure clients to include credentials per request via headers or query params. The server resolves credentials fresh per request so different clients can target different Jira instances.

CLI (optional)

jira-mcp-cli calls the same 8 tools from a shell instead of an MCP client — useful for agents and scripts that would rather run a command than speak MCP. It drives the server in-process via fastmcp.Client (no subprocess, no socket), so it runs the exact same tool code and middleware as MCP.

Installed alongside the package as the jira-mcp-cli entry point. Credentials come from the environment only (JIRA_BASE_URL, JIRA_USERNAME, JIRA_API_TOKEN, optional JIRA_DEFAULT_PROJECT) — there are no credential flags, and no .env file is read.

Output contract:

• call-tool and read-resource write to stdout verbatim and nothing else — read-resource emits the resource's text, so JSON resources pipe cleanly too. Non-text blob placeholders go to stderr. Logs, warnings, and tool errors also go to stderr, so | jq is safe. The discovery commands (list-tools, list-resources, list-prompts, get-prompt) print human-readable text, not JSON — use SKILL.md or --help for the flag reference instead of parsing them
• Exit codes: 0 the tool call succeeded, 1 the tool returned an error, 2 the command refused to run — an issue_delete missing --yes, or a malformed JSON-typed flag. A 0 exit can still carry "valid": false in the body — that's a validation result, not a failure
• Boolean flags negate with a --no- prefix, e.g. --no-include-comments
• List flags are repeated, not space-separated: --labels bug --labels p1 (--labels a b is a parse error)
• Flags documented as (JSON string) take a JSON literal, e.g. --custom-fields '{"customfield_10001": "value"}'

issue_delete requires --yes. The server normally asks for confirmation via Elicitation, which a CLI can't answer — issue_delete's except-branch proceeds without confirmation when the client can't elicit, so --yes is the explicit stand-in for that prompt. Without it the command exits 2 and does nothing.

Examples:

$ jira-mcp-cli call-tool issue_get --issue-key PROJ-123 --verbosity summary
{"key": "PROJ-123", "summary": "...", ...}

$ jira-mcp-cli call-tool issue_validate_fields --project-key PROJ --priority High
{"valid": false, "errors": [{"field": "priority", "message": "Invalid priority 'High'", ...}]}

$ jira-mcp-cli call-tool issue_search --jql "project = PROJ AND status = 'In Progress'" | jq -r '.issues[].key'

$ jira-mcp-cli call-tool issue_delete --issue-key PROJ-999 --yes

Full flag reference for every command: SKILL.md. Regenerate both after tool schemas change with python scripts/regen_cli.py (--check to verify without writing).

Available Tools

Issue Operations

issue_get — Get a single issue

issue_get(
    issue_key="PROJ-123",
    verbosity="full",          # "ids" | "summary" | "full" (default: "full")
    include_transitions=True,
    include_comments=True,
)

Verbosity levels:

• ids — issue key only (minimal tokens)
• summary — key fields: summary, status, assignee, priority, dates
• full — complete details including description, comments, transitions

issue_search — Search with JQL

issue_search(
    jql="project = PROJ AND status = 'In Progress'",
    verbosity="summary",       # default: "summary"
    max_results=50,
)

Common JQL patterns:

# My open issues
issue_search(jql="assignee = currentUser() AND statusCategory != Done")

# High priority bugs
issue_search(jql="priority = High AND issuetype = Bug")

# Sprint backlog
issue_search(jql="sprint in openSprints() AND project = PROJ")

Pagination and count:

• Jira's /search/jql endpoint is token-paginated, not offset-paginated. Read nextPageToken from a response and pass it back as next_page_token to get the next page; stop when isLast is true. Passing a non-zero start_at raises an error naming next_page_token instead of silently returning page 1 again — that used to happen because Jira accepts and discards startAt.
• total in the response is the number of issues in this page, suffixed + when a further page exists. It is not a match count.
• Set include_count=True to get an actual match count in match_count — one extra request to Jira's approximate-count endpoint, so it's opt-in. If that request fails, the search still succeeds and match_count comes back null, never 0, so a caller can tell "couldn't determine" from "zero matches".
• Passing fields returns raw Jira issue objects under .issues[].fields with only those fields populated — absent means you did not ask for it, null means Jira has no value. verbosity="full" is no longer required alongside fields; verbosity="ids" still wins and returns just the keys.

issue_create — Create a new issue

Supports interactive Elicitation for missing required fields (project_key, issue_type, summary).

issue_create(
    project_key="PROJ",
    issue_type="Story",        # case-insensitive; "story", "bug", "task" all work
    summary="Implement login feature",
    description="## Overview\nDetailed description with **markdown** support",
    priority="high",           # aliases: "high"→"High", "critical"→"Highest"
    assignee="John Smith",     # display name, email, or account ID
    components=["frontend"],   # component names auto-resolved to IDs
    labels=["backend", "auth"],
    auto_normalize=True,       # default; normalizes all field values
)

issue_update — Update fields, transition status, and add comments (unified)

# Update fields
issue_update(issue_key="PROJ-123", priority="High", labels=["backend"])

# Transition status (by name or ID)
issue_update(issue_key="PROJ-123", transition="In Progress")

# Add a comment
issue_update(issue_key="PROJ-123", comment="Review complete")

# Combined: transition + assign + comment in one call
issue_update(
    issue_key="PROJ-123",
    transition="In Progress",
    assignee="dev@example.com",
    comment="Starting work on this",
)

issue_delete — Delete an issue

Uses Elicitation to confirm before deleting.

issue_delete(issue_key="PROJ-123", delete_subtasks=False)

issue_comment — Add a comment

issue_comment(
    issue_key="PROJ-123",
    body="Looks good to me — merging.",
    mentions=["Jason Schulz"],  # display name, email, or account ID
)

You can also write the mention directly into the body, where you want it to appear:

issue_comment(
    issue_key="PROJ-123",
    body="cc @[Jason Schulz] — the fix is on `main`.",
)

Mentions are verified against Jira before the comment is posted. An unknown or ambiguous mention fails the call — nothing is posted — and the error names the failed query plus the candidate users. On success the response carries mentions_resolved (query, account_id, display_name) so callers confirm who was tagged without re-reading the comment.

This matters because Jira does not reject a bad mention: a comment carrying a fabricated account ID posts successfully and renders as inert text that notifies nobody. Refusing up front is the only way to prevent that.

Body references are handled by intent:

Written in the body	Behavior
@[Full Name]	Explicit — must resolve, or the comment is refused
@Name, @Name Surname, @user@host.com	Converted to a real mention when it matches exactly one user
Anything that doesn't resolve	Left as the literal text you wrote, and returned in mentions_unmatched
Code spans, code blocks, link text	Never touched

The same verification applies to a pre-rendered ADF body containing hand-built mention nodes, and to issue_update(comment=..., mentions=[...]) — where resolution happens before any write, so a bad mention means no transition, no field update and no comment rather than a half-applied change.

Project Operations

project_get — Get project details

project_get(
    project_key="PROJ",
    verbosity="summary",
    include_components=True,
    include_versions=True,
)

Validation

issue_validate_fields — Validate and normalize fields before creation

Use this to preview normalization and catch errors before calling issue_create:

result = issue_validate_fields(
    project_key="PROJ",
    issue_type="bug",
    priority="high",
    assignee="John",
    components=["frontend"],
)

# result["valid"] == True/False
# result["normalized"] == normalized field values
# result["errors"] == list of field errors with suggestions

Resource Endpoints

Resource Templates (Parameterized)

Read any Jira entity by URI — MCP clients discover these via list_resource_templates():

URI Template	Description
issue://{issue_key}	Get any issue by key (e.g., issue://PROJ-123)
project://{project_key}	Get any project by key (e.g., project://PROJ)

Static Resources

Access workspace data through fixed MCP resource URIs:

URI	Description
current-user://info	Current authenticated Jira user
current-user://issues	Issues assigned to the current user
workspace://users	Active users in the workspace
workspace://projects	Accessible Jira projects
workspace://recent-issues	Issues updated in the last 7 days
workspace://verbose-metadata	Combined metadata: priorities and statuses
workspace://issue-creation-metadata	Issue types per project + priorities + assignees
adf-examples://	ADF formatting examples and reference

ADF (Atlassian Document Format) Support

The server automatically converts plain text and Markdown to ADF format (via marklassian) — no manual formatting required. Headings, bold/italic/strikethrough, nested lists, code blocks, blockquotes, links, tables, and GFM task lists are all supported. Content that is already ADF passes through untouched — whether given as an ADF object or as a serialized ADF JSON string.

# Plain text
description = "Simple text description"

# Markdown (headings, bold, lists, code blocks, links all supported)
description = """
## Overview
This issue implements **important** features.

### Acceptance Criteria
- First criterion
- Second criterion

```python
def example():
    return "code block"

"""

## Architecture

The server uses a single FastMCP instance with direct tool/resource/prompt registration:

atlassian-jira-mcp-server/ ├── server.py # Single FastMCP server entry point ├── src/ │ ├── client/ │ │ ├── jira.py # JiraClient — per-request HTTP client │ │ ├── config.py # TenantConfig — multi-source credential resolution │ │ └── errors.py # Typed error classes (PermanentError, etc.) │ ├── tools/ │ │ ├── issue.py # issue_get, issue_search, issue_create, issue_update, │ │ │ # issue_delete, issue_comment │ │ ├── project.py # project_get │ │ ├── validation.py # issue_validate_fields │ │ └── helpers.py # Shared utilities (get_jira_client, elicit_or_error) │ ├── resources/ │ │ ├── static.py # ADF examples resource │ │ └── workspace.py # Dynamic workspace/user/project resources │ ├── prompts/ │ │ └── workflows.py # Workflow guidance prompts │ ├── middleware/ │ │ ├── auth.py # BearerAuthMiddleware — MCP endpoint token validation │ │ └── tenant.py # TenantMiddleware — per-request credential resolution │ └── utilities/ │ ├── adf.py # Markdown→ADF (marklassian) + ADF builders/rendering │ ├── resolvers.py # Component/transition name→ID resolution with caching │ └── formatting.py # Issue/project response formatting + verbosity ├── tests/ # 321 tests (unit + FastMCP Client integration) ├── Dockerfile ├── docker-compose.yml ├── pyproject.toml └── requirements.txt

### Key Design Patterns

1. **Single-Server Architecture** — no mounted sub-servers; tools, resources, and prompts register directly on one `FastMCP` instance
2. **Middleware Stack** — `BearerAuthMiddleware` (endpoint auth) → `TenantMiddleware` (per-request credential injection)
3. **Per-Request JiraClient** — no global HTTP client; each tool call gets a fresh `JiraClient` scoped to the request's `TenantConfig`
4. **Multi-Tenant by Default** — HTTP mode supports any number of Jira tenants with zero configuration changes
5. **Elicitation** — `issue_create` and `issue_delete` use `ctx.elicit()` for legacy-protocol clients. Modern MCP clients supply the required creation arguments directly; interactive deletion confirmation is unavailable on that protocol.

## Development

### Running Tests

```bash
# Run full test suite
pytest tests/ -v

# Run a specific test file
pytest tests/test_integration.py -v

# With venv
.venv/bin/pytest tests/ -v

The test suite includes:

• Unit tests for individual functions (test_client.py, test_config.py, test_errors.py, test_tools_*.py, etc.)
• FastMCP Client integration tests (test_integration.py) — exercise the full MCP stack in-memory using FastMCP's Client without a running server
• Middleware tests (test_middleware.py) — validate auth and tenant credential resolution

After Code Changes

# Reinstall uv tool
uv tool uninstall atlassian-jira-mcp-server && uv tool install . --reinstall

# Rebuild Docker image
docker-compose down && docker-compose build && docker-compose up -d

Verifying Imports

python -c "from src.tools import register_tools; print('OK')"
python -c "from server import create_server; print('OK')"

Adding New Tools

1. Implement in src/tools/ (e.g., src/tools/issue.py):

@mcp.tool
async def issue_new_operation(ctx: Context, issue_key: str) -> dict:
    """Tool description shown to the LLM."""
    async with await get_jira_client(ctx) as client:
        result = await client.request("GET", f"issue/{issue_key}/subtasks")
        return result

2. Register in src/tools/__init__.py:

from src.tools import new_module
new_module.register(mcp)

Error Handling

The server distinguishes temporary from permanent errors:

Error Type	Retry?	Example
Connection error	Yes	"Connection Error: Unable to connect..."
Timeout	Yes	"Timeout Error: Request timed out..."
Session error	Yes	"No valid session ID provided"
Permission error (403)	No	"Permission Error (HTTP 403): ..."
Validation error (400)	No	"Jira API Error: field 'x' is required"
Not found (404)	No	Project or issue does not exist

Troubleshooting

"externally-managed-environment" Error (pip)

Use uv tool install (Method 2) or a virtual environment (Method 3) instead of a system pip install.

Python Not Found with pyenv

# Set a global Python version
pyenv global 3.12.11

# Or use python3 explicitly
python3 -m venv .venv

Authentication Failures

• Verify JIRA_BASE_URL includes https:// and no trailing slash
• Confirm the API token belongs to the same email as JIRA_USERNAME
• Check that the token has not expired in Atlassian account settings

Permission Errors (HTTP 403)

• Confirm the Jira user has Browse Project and the relevant Create/Edit/Delete permissions
• Check that the issue type is available in the target project

Contributing

Contributions are welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality (pytest tests/ -v must pass)
4. Submit a pull request

License

MIT License — see LICENSE file for details.

Support

• Report issues
• Jira Cloud API Documentation
• MCP Documentation
• FastMCP Documentation