jira-mcp

A Model Context Protocol (MCP) server for Atlassian Jira (self-hosted Server / Data Center), written in Python. It lets MCP-compatible clients (Claude Desktop, Claude Code, Cursor, etc.) search, read, and manage Jira issues, projects, comments, workflow transitions, worklogs, and agile boards.

Targets the company's self-hosted Jira at (e.g. https://works.digikala.com) over the REST API v2 with HTTP basic auth — you only supply your PAT and host.

Features

| Tool | Description | | ------------------ | ----------------------------------------------- | | get_current_user | search_issues | get_issue | get_comments | list_transitions | list_projects | get_project | search_users | list_boards | list_sprints | create_issue | update_issue | add_comment | transition_issue | assign_issue | add_worklog | link_issues | delete_issue | Who am I? (connectivity check) | | Search issues with JQL | | Fetch one issue (optionally with comments) | | List an issue's comments | | Available workflow transitions for an issue | | List accessible projects | | Fetch one project | | Find users (returns account ids for assignment) | | List agile boards | | List sprints on a board | | Create an issue | | Update fields on an issue | | Comment on an issue | | Move an issue through its workflow | | Assign / unassign an issue | | Log time against an issue | | Link two issues | | Delete an issue (guarded) |

Write tools can be disabled entirely with JIRA_READ_ONLY=true.

Installation

Requires Python 3.10+. The package is distributed via GitHub.

Install as a tool (recommended)

Install once into an isolated environment — fast to launch afterwards (no re-download or rebuild per run), which matters when an MCP client spawns the server repeatedly:

uv tool install git+https://github.com/alirezahematidev/jira-mcp
# or:
pipx install git+https://github.com/alirezahematidev/jira-mcp

This puts a jira-mcp executable on your PATH. Find it with which jira-mcp.

To update later: uv tool upgrade jira-mcp (or pipx upgrade jira-mcp).

From source (development)

git clone https://github.com/alirezahematidev/jira-mcp
cd jira-mcp
uv pip install -e ".[dev]"   # or: pip install -e ".[dev]"

Tip: avoid uvx --from git+...jira-mcp in an MCP client config — it re-resolves the package on every launch and is noticeably slow. Install once (above) and point the client at the installed executable instead.

Configuration

Provide your Jira host and a personal access token (PAT) via environment variables (or a .env file; copy .env.example to .env):

JIRA_HOST=your-jira-host
JIRA_PAT=your-personal-access-token

Generate the PAT from your self-hosted Jira account settings.

Running

jira-mcp          # console script (stdio transport)
python -m jira_mcp # equivalent

The server speaks MCP over stdio, so it's normally launched by an MCP client rather than run by hand.

Claude Desktop / Claude Code

Add to your MCP config (e.g. .mcp.json):

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp",
      "env": {
        "JIRA_HOST": "your-jira-host",
        "JIRA_PAT": "your-personal-access-token"
      }
    }
  }
}

If the client can't find jira-mcp on its PATH, use the absolute path from which jira-mcp (e.g. /Users/you/.local/bin/jira-mcp) as "command".

Usage notes

JQL is the most powerful entry point, e.g. project = PROJ AND assignee = currentUser() AND status != Done ORDER BY updated DESC.
Assigning users: assignee is a username — call search_users first to find it.
Transitions: status names aren't passed directly. Call list_transitions to get a valid transition_id, then transition_issue.
Rich text: descriptions and comments are plain text (Jira wiki markup is accepted).

Development

uv pip install -e ".[dev]"
pytest          # run the test suite
ruff check .    # lint

The tests mock the Jira HTTP API with respx, so no live Jira instance is needed.

Building & publishing

uv build              # produces dist/*.whl and dist/*.tar.gz
uvx twine check dist/* # validate package metadata

git tag v0.1.0 && git push origin v0.1.0

License

MIT

MCP Servers