Jira 问题管理 MCP 服务

python-jira-plus-mcp

An MCP server that lets any MCP client, work with Jira Cloud and Jira Data Center: search and read issues, then optionally create, update, comment, transition, link and delete them.

It is a thin layer over python-jira-plus, which does the Jira work (validation, pagination, error handling). This package only defines the tools and shapes their results for a model.

Requirements

• uv (it provides uvx, and installs Python 3.12+ if needed)
• git, to install straight from GitHub
• A Jira account with an API token (Cloud) or a personal access token (Data Center)

curl -LsSf https://astral.sh/uv/install.sh | sh   # once, if uv is not installed

Quick start

Claude Desktop

Add the server to claude_desktop_config.json, then restart the app:

{
  "mcpServers": {
    "jira": {
      "command": "/Users/you/.local/bin/uvx",
      "args": [
        "--from", "git+https://github.com/aviz92/python-jira-plus-mcp@main",
        "python-jira-plus-mcp"
      ],
      "env": {
        "JIRA_BASE_URL": "your-site.atlassian.net",
        "JIRA_USER_NAME": "you@example.com",
        "JIRA_TOKEN": "your-api-token",
        "JIRA_DEPLOYMENT": "cloud",
        "JIRA_MCP_READ_ONLY": "false",
        "JIRA_MCP_ENABLE_DELETE": "true"
      }
    }
  }
}

• Use the full path to uvx (which uvx prints it). Claude Desktop does not load your shell's PATH.
• With @main, every restart of the app picks up the latest commit on main. To stay on one version, pin a tag instead, e.g. @v0.1.0.
• The token lives only in this local file. Never commit it.

Authentication

JIRA_BASE_URL may include the scheme; https:// is assumed when it doesn't.

Configuration

All settings are environment variables (or a .env file in the working directory; see env.template).

Tools

Names of issue types, transitions and link types are matched case-insensitively. Invalid values are rejected with the list of allowed values, so the model can correct itself.

Enabling writes

Add to the server's env:

"JIRA_MCP_READ_ONLY": "false"

This registers the six write tools. Deletion has its own switch because it cannot be undone:

"JIRA_MCP_ENABLE_DELETE": "true"

Access and safety

• The server can do whatever the token's Jira user can do. To limit the model to certain projects, give it a dedicated Jira user whose permissions cover only those projects; Jira then enforces it on every request.
• Read-only by default, and deletion needs a second, explicit switch.
• Issue keys are validated before any request, so a crafted key such as PROJ-1/../myself cannot reach another Jira endpoint.
• upload_attachment is not exposed: a local file path means nothing across the MCP boundary.

Notes

• Jira Cloud rejects searches without a restriction. A query like ORDER BY created DESC alone fails with "Unbounded JQL queries are not allowed here". Add a condition, e.g. project = KAN ORDER BY created DESC. Data Center accepts unrestricted queries.
• To create an issue, the model calls jira_get_create_fields, then jira_get_allowed_values for each field it needs that has has_allowed_values, then jira_create_issue.
• Errors come back as tool errors carrying Jira's own message (e.g. Jira error 404: Issue does not exist ...).

Docker and the HTTP transport (experimental)

docker build -t python-jira-plus-mcp .
docker run -i --rm -e JIRA_BASE_URL -e JIRA_USER_NAME -e JIRA_TOKEN python-jira-plus-mcp

The image runs over stdio by default. JIRA_MCP_TRANSPORT=streamable-http serves on JIRA_MCP_HOST:JIRA_MCP_PORT instead; in Docker, set JIRA_MCP_HOST=0.0.0.0 and publish the port.

The HTTP transport has no authentication. Anyone who can reach the port acts with the configured Jira token. Bind to loopback, or put an authenticating reverse proxy in front.

Development

git clone https://github.com/aviz92/python-jira-plus-mcp
cd python-jira-plus-mcp
uv sync --group dev
uv run pytest                                 # unit tests; integration tests are skipped
uv run pre-commit run --files <changed_files>

To run a client against your working copy, point it at the checkout:

"command": "/Users/you/.local/bin/uv",
"args": ["--directory", "/path/to/python-jira-plus-mcp", "run", "python-jira-plus-mcp"]

Integration tests

uv run pytest -m integration runs against a real Jira, with the JIRA_* credentials from the environment or .env. The write tests also need a sandbox project; the issues they create are deleted afterwards:

License

MIT