Jira MCP Server

Production-ready Jira MCP server exposing Jira projects, issues, sprints, users, attachments, and worklogs as Model Context Protocol tools, resources, and prompts — to any MCP client (Claude Desktop, Claude Code, Cursor, VS Code) over stdio (local) or HTTP/SSE / Streamable HTTP (remote or team-shared).

┌──────────────────────────────────────────────────────────────────┐
│                         MCP Client                                │
│   Claude Desktop / Claude Code / Cursor / VS Code / custom        │
└───────────────┬───────────────────────────────────┬──────────────┘
                │ stdio (JSON-RPC over stdin/stdout) │   HTTP (SSE/Streamable)
                ▼                                    ▼
        ┌──────────────────┐              ┌──────────────────────┐
        │   stdio transport │              │   HTTP transport     │
        │   (default)       │              │   /sse /mcp /health  │
        └───────┬──────────┘              └──────────┬───────────┘
                │       same registered server        │
                ▼                                     ▼
        ┌──────────────────────────────────────────────────────────┐
        │               jira_mcp_server.server.create_server()      │
        │   27 tools · 4 resources · 4 prompts (transport-agnostic) │
        └───────────────────────────────┬──────────────────────────┘
                                        ▼
                       ┌────────────────────────────────┐
                       │  JiraClient (httpx async)       │
                       │  auth · rate-limit · retry      │
                       └────────────────┬───────────────┘
                                        ▼
                          Jira REST API / Agile API (HTTPS)

Features

• Dual transports — stdio for local integration; HTTP with SSE and Streamable HTTP for remote/team deployments, switchable via CLI flag or MCP_TRANSPORT.

• Dual Jira auth — Jira Cloud (basic: email + API token) and Jira Data Center / Server (Bearer PAT).

• Security first — HTTPS-only (JIRA_BASE_URL refuses plaintext), no credentials in logs (token masking), client-side token-bucket rate limiting, project whitelist enforcement, tool-level CRUD permission control (JIRA_TOOLS), confirm guard on deletion, attachment size limits, optional static Bearer auth for the HTTP transport, CORS control.

• Automatic retry + pagination — 429/5xx retry with exponential backoff; list endpoints paginate automatically.

• ADF support — plain-text → Atlassian Document Format conversion for descriptions/comments; ADF → text rendering for reads.

• Type-safe — Pydantic-validated tool schemas and config.

• Docker ready — Dockerfile + docker-compose.yml.

Related MCP server: Jira MCP Server

Requirements

• Python 3.11+ (3.12 recommended).

• A Jira instance:

  • Jira Cloud — an API token (email + token for Basic auth), and the user should have at least: Browse projects, Create issues, Edit issues, Manage attachments, Manage worklogs, and (for board/sprint tools) access to the relevant boards.

  • Jira Data Center / Server — a Personal Access Token, and a TLS-terminated HTTPS endpoint (the server refuses plaintext).

Token management: create tokens per environment, scope them to the least privilege you need, and rotate them regularly. Never commit .env. If a token must be granted broad Jira permissions, pair it with JIRA_TOOLS (see Tool permissions) to restrict which of those permissions MCP clients can actually drive.

Installation

1. pip

pip install jira-mcp-server

2. uv

uv pip install jira-mcp-server

3. From source

git clone https://github.com/your-org/jira-mcp-server.git
cd jira-mcp-server
python -m venv .venv
source .venv/bin/activate      # Linux / macOS
pip install -e ".[dev]"

On Windows, use PowerShell instead:

git clone https://github.com/your-org/jira-mcp-server.git
cd jira-mcp-server
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

or (CMD):

git clone https://github.com/your-org/jira-mcp-server.git
cd jira-mcp-server
python -m venv .venv
.\.venv\Scripts\activate.bat
python -m pip install -e ".[dev]"

A successful editable install automatically writes the jira-mcp-server console entry point — and on Windows the jira-mcp-server.exe launcher — into the active environment's Scripts directory. See Building the jira-mcp-server.exe console script.

4. Docker (HTTP mode)

docker run -p 8080:8080 \
  -e JIRA_BASE_URL=https://your-domain.atlassian.net \
  -e JIRA_API_TOKEN=your-token \
  -e JIRA_USER_EMAIL=your@email.com \
  -e JIRA_TOOLS=read,create,update \
  jira-mcp-server:latest

See Docker deployment for full details.

Quick start (3 minutes)

stdio mode — Claude Desktop

Add this to Claude Desktop's claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "jira-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_AUTH_METHOD": "basic",
        "JIRA_USER_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_TOOLS": "read,create,update"
      }
    }
  }
}

Restart Claude Desktop, open a conversation, and try:

"List my Jira projects." → the server calls jira_list_projects. "Create a Bug in PROJ titled 'Login fails on Safari'." → jira_create_issue.

stdio mode — Cursor / VS Code

The same mcpServers block goes into the MCP configuration of your editor (~/.cursor/mcp.json for Cursor, or the VS Code MCP panel). The command stays jira-mcp-server with the same env.

HTTP/SSE mode

Start the service on port 8080:

jira-mcp-server --transport http --port 8080
# or using env vars
export MCP_TRANSPORT=http
export MCP_HOST=127.0.0.1
export MCP_PORT=8080
export JIRA_TOOLS=read,create,update
jira-mcp-server

Connect from any SSE-capable MCP client:

{
  "mcpServers": {
    "jira": {
      "url": "http://127.0.0.1:8080/sse",
      "headers": { "Authorization": "Bearer your-secret-token" }
    }
  }
}

Check it is up:

curl http://127.0.0.1:8080/health
# {"status":"healthy","server":"jira-mcp-server","version":"0.1.0","transport":"http","jira_configured":true}

To require a client token (recommended for anything beyond localhost), start with:

jira-mcp-server --transport http --port 8080 --auth-mode token --server-token your-secret-token

The token protects who can connect to the MCP server; the Jira credentials (JIRA_API_TOKEN) still govern what the server can do in Jira.

Client token (HTTP 认证)

In HTTP/SSE mode you can require clients to authenticate with a static Client token before the MCP session is allowed. Think of it as the server's "front door" password: it decides who may connect, whereas JIRA_API_TOKEN decides what Jira operations the server may perform.

Create a client token

Any reasonably long random string works (the server compares the presented token by exact string equality). Generate one with secrets, so it cannot be guessed:

# Python is cross-platform and already available (the project requires it).
python -c "import secrets; print(secrets.token_urlsafe(32))"
# e.g. 9xKp2vY6QwE3rT8zU1iA0sD5fG7hJ4kN6lM9oP2qR5uW8

Configure the server side

Enable token auth by supplying the same client token through one of:

# Option A — CLI flag (highest precedence).
jira-mcp-server --transport http --port 8080 \
  --auth-mode token --server-token 9xKp2vY6QwE3rT8zU1iA0sD5fG7hJ4kN6lM9oP2qR5uW8

# Option B — environment variables (equivalent; avoids the token in shell history).
export MCP_AUTH_MODE=token
export MCP_SERVER_TOKEN=9xKp2vY6QwE3rT8zU1iA0sD5fG7hJ4kN6lM9oP2qR5uW8
jira-mcp-server --transport http --port 8080

# Option C — docker-compose (environment passthrough, already wired).
environment:
  JIRA_TOOLS: ${JIRA_TOOLS:-}
  MCP_TRANSPORT: http
  MCP_AUTH_MODE: token
  MCP_SERVER_TOKEN: ${MCP_SERVER_TOKEN:-}

Set both MCP_AUTH_MODE=token and MCP_SERVER_TOKEN together. Note the exact behavior when one is missing:

• MCP_AUTH_MODE=token and no MCP_SERVER_TOKEN → the server logs a warning at startup and serves unauthenticated (no auth middleware is attached). This is a footgun: if you intend to require a client token, set the token too.

• MCP_AUTH_MODE=none (or unset) → no client auth at all, regardless of MCP_SERVER_TOKEN.

Configure the client side

The client sends the same token in an Authorization: Bearer … header:

{
  "mcpServers": {
    "jira": {
      "url": "http://127.0.0.1:8080/sse",
      "headers": { "Authorization": "Bearer 9xKp2vY6QwE3rT8zU1iA0sD5fG7hJ4kN6lM9oP2qR5uW8" }
    }
  }
}

Claude Code uses --header; Claude Desktop and Cursor/VS Code use the headers map above:

claude mcp add jira --scope project \
  --url http://127.0.0.1:8080/sse \
  --header "Authorization: Bearer 9xKp2vY6QwE3rT8zU1iA0sD5fG7hJ4kN6lM9oP2qR5uW8"

Sanity-check both sides with curl:

curl -i http://127.0.0.1:8080/health | head -1        # 401 without a token
curl -i -H "Authorization: Bearer 9xKp2vY6QwE3rT8zU1iA0sD5fG7hJ4kN6lM9oP2qR5uW8" \
  http://127.0.0.1:8080/health | head -1              # 200 with the token

Rotate the token

Generate a new token (see above), restart the server with it, and update every client config. The two-layer layout (server process holds the Jira credentials, clients only hold the client token) means rotating the client token does not require reissuing Jira tokens.

Connecting to Claude Code

Claude Code registers local MCP servers as stdio commands or remote HTTP URLs. With the package installed (so jira-mcp-server is on PATH — on Windows that means D:\develop\Python312\Scripts\jira-mcp-server.exe exists). If the executable is not on your machine yet, generate it from source first (see Building the jira-mcp-server.exe console script), then return here. From the project root:

stdio (recommended for a single user)

claude mcp add jira --scope project \
  --env JIRA_BASE_URL=https://your-domain.atlassian.net \
  --env JIRA_USER_EMAIL=you@email.com \
  --env JIRA_AUTH_METHOD=basic \
  --env JIRA_API_TOKEN=ATATT3YOUR_REAL_TOKEN \
  --env JIRA_TOOLS=read,create,update \
  jira-mcp-server

• JIRA_API_TOKEN is required: the server refuses to start with JIRA_AUTH_METHOD=basic unless an API token is present. Include it in the command (or see the safer alternatives below).

• Omitting --scope project writes to the global config ~/.claude/mcp.json (all projects); --scope project writes a project-level .mcp.json so credentials are not shared across projects.

• You can also pass --scope local to store the entry in ~/.claude.json for the current user only (3.x).

• Where does the token come from? The server reads credentials from the environment that the stdio child process inherits when Claude Code starts it. Two ways to supply it:

  1. --env JIRA_API_TOKEN=... in the command above (easiest; token is stored in plain text in .mcp.json/mcp.json).

  2. Keep it out of the config by exporting it in the shell that launches claude (then omit the --env JIRA_API_TOKEN line). The child process inherits the exported variable:

     export JIRA_BASE_URL=https://your-domain.atlassian.net
     export JIRA_USER_EMAIL=you@email.com
     export JIRA_API_TOKEN=ATATT3YOUR_REAL_TOKEN
     export JIRA_AUTH_METHOD=basic
     export JIRA_TOOLS=read,create,update
     claude mcp add jira --scope project \
       --env JIRA_BASE_URL="$JIRA_BASE_URL" \
       --env JIRA_USER_EMAIL="$JIRA_USER_EMAIL" \
       --env JIRA_AUTH_METHOD=basic \
       --env JIRA_TOOLS="$JIRA_TOOLS" \
       jira-mcp-server

  3. A project-root .env file is not relied upon: the server tries to load it lazily, but only when a code layout allows it, and that is unreliable across installs. Use options 1 or 2.

Verify:

claude mcp list            # jira: Command - ✔ Connected
claude mcp get jira        # shows the resolved command + env

Restart Claude Code (or run /mcp to check connection status) and start a new session — the jira_* tools will be available.

If the server fails to start with Jira API Token is required when JIRA_AUTH_METHOD=basic, the most likely cause is that JIRA_API_TOKEN was not visible to the stdio child process. Either add it with --env JIRA_API_TOKEN=... or export it before launching claude.

HTTP/SSE (team-shared / multi-client)

# terminal 1: start the service (it holds the Jira credentials)
export JIRA_BASE_URL=https://your-domain.atlassian.net
export JIRA_USER_EMAIL=you@email.com
export JIRA_API_TOKEN=<token>
export JIRA_TOOLS=read,create,update
jira-mcp-server --transport http --host 127.0.0.1 --port 8080 \
  --auth-mode token --server-token <client-token>

# terminal 2: register the URL in Claude Code
claude mcp add jira --scope project \
  --url http://127.0.0.1:8080/sse \
  --header "Authorization: Bearer <client-token>"

This gives two-layer auth: <client-token> guards who may connect to the MCP server, JIRA_API_TOKEN governs what it can do in Jira. The <client-token> placeholder is the shared secret you generate yourself (see Client token (HTTP 认证)) — it is not the Jira API token.

Because the Jira credentials live in the server process (terminal 1), they never appear in Claude Code's mcp.json/.mcp.json — an advantage of the HTTP layout when you want to keep JIRA_API_TOKEN out of the client config.

Environment variables

Copy .env.example → .env for local dev. CLI flags take precedence over environment variables.

CLI reference

jira-mcp-server [OPTIONS]

Options:
  --transport [stdio|http|http-streamable]  Transport mode (default: stdio; env MCP_TRANSPORT)
  --host TEXT                HTTP bind host (default: 127.0.0.1; env MCP_HOST)
  --port INTEGER             HTTP bind port (default: 8080; env MCP_PORT)
  --auth-mode [none|token]   HTTP client auth (default: none; env MCP_AUTH_MODE)
  --server-token TEXT        Bearer token for client connections (env MCP_SERVER_TOKEN)
  --cors-origins TEXT        CORS origins, comma-separated (default: *)
  --log-level [DEBUG|INFO|WARNING|ERROR]  Logging level (env MCP_LOG_LEVEL)
  --log-file TEXT            Optional log file (env MCP_LOG_FILE)
  --version                  Print version and exit
  --help                     Show help

Transports

Tools

All tools return JSON text. On failure they return {"isError": true, "content": [{"type": "text", "text": "Jira API Error [403]: …"}]}.

Issues

Sprints / Boards

Projects

Users

Attachments

Worklogs

Example return value

jira_create_issue(project_key="PROJ", summary="Login fails", issue_type="Bug") →

{"issue":{"id":"10004","key":"PROJ-9","self":"https://acme.atlassian.net/rest/api/3/issue/10004"}}

Resources

MCP resources expose read-only context the model can reference:

Reading jira://project/PROJ/meta, for example, returns JSON such as:

{"projects": [{"key": "PROJ", "issuetypes": [{"name": "Bug", "fields": {"summary": {"required": true}}}]}]}

Prompts

Prompts guide the model through structured workflows:

Example — after invoking create_bug_report the model will assemble the details and call jira_create_issue automatically.

Tool permissions (CRUD control)

A Jira API token is often granted broad rights (e.g. create, edit, delete), but a given deployment may only need a subset of them. Rather than maintaining a separate token per workflow, the server can restrict which tools it exposes via JIRA_TOOLS. Disabled tools are never registered, so clients cannot see them in tools/list — an over-permissioned token can still only drive the tools you opt in to.

JIRA_TOOLS is a comma-separated allowlist of category keywords and/or exact tool names. Empty or unset keeps today's behavior (all tools enabled).

Examples:

# Read-only deployment (the Jira token may be full-admin; clients can only read).
JIRA_TOOLS=read

# Everything except deletion.
JIRA_TOOLS=read,create,update

# Read + exactly one extra tool.
JIRA_TOOLS=read,jira_add_comment

Notes:

• Values are case-insensitive; entries must be a known keyword or a real tool name. A typo (e.g. JIRA_TOOLS=rede) fails startup instead of silently dropping tools.

• The current tool-category mapping is:

  Category	Tools
  read	jira_get_issue, jira_get_transitions, jira_get_comments, jira_get_issue_links, jira_get_issue_meta, jira_get_project_meta, jira_search_issues, jira_search_issues_jql_only, jira_list_projects, jira_get_project, jira_get_project_versions, jira_list_boards, jira_list_sprints, jira_get_sprint_issues, jira_list_attachments, jira_get_worklogs, jira_search_users, jira_get_myself
  create	jira_create_issue, jira_add_comment, jira_add_attachment, jira_add_worklog, jira_link_issues, jira_move_issues_to_sprint
  update	jira_update_issue, jira_transition_issue
  delete	jira_delete_issue

This layer protects the tool surface, not Jira itself. Authorization also follows JIRA_PROJECT_KEYS: combine both to scope by operation and by project (e.g. JIRA_TOOLS=read JIRA_PROJECT_KEYS=ENG = read-only on one project).

Security & best practices

• HTTPS only — JIRA_BASE_URL must start with https://; plaintext URLs are refused at startup.

• No hardcoded credentials — everything comes from the environment.

• Token masking — tokens are logged as ATATT****, never in full.

• Project whitelist — set JIRA_PROJECT_KEYS=ENG,SALES to scope all JQL searches and block writes to other projects.

• Tool whitelist — JIRA_TOOLS restricts which tools are exposed (see Tool permissions); use it to keep an over-permissioned token from driving destructive tools.

• Deletion guard — jira_delete_issue requires confirm=true.

• Attachment guard — uploads over 10 MiB are rejected.

• Rate limiting — client-side token bucket (default 100 req/min).

• HTTP transport auth — enable --auth-mode token and a strong MCP_SERVER_TOKEN for anything networked.

• Production HTTP — bind 127.0.0.1 and put the server behind a reverse proxy (nginx/Caddy) that terminates TLS; restrict the port to the proxy and approved clients; enable request/audit logging.

• Rotate tokens — use distinct tokens per environment, rotate quarterly (or on any suspected leak), and remove users from Jira when they leave.

• Least privilege — give the token user only the Jira permissions the workflows need (browse + create/edit specific projects; not Global Admin).

Docker deployment

Dockerfile (included)

FROM python:3.12-slim
WORKDIR /app
COPY pyproject.toml README.md ./
COPY src/ src/
RUN pip install --no-cache-dir .
ENV MCP_TRANSPORT=http MCP_HOST=0.0.0.0 MCP_PORT=8080 JIRA_AUTH_METHOD=basic JIRA_TOOLS=read,create,update
EXPOSE 8080
CMD ["jira-mcp-server", "--transport", "http", "--host", "0.0.0.0", "--port", "8080"]

docker-compose.yml (included)

services:
  jira-mcp:
    build: .
    ports: ["8080:8080"]
    environment:
      JIRA_BASE_URL: ${JIRA_BASE_URL}
      JIRA_API_TOKEN: ${JIRA_API_TOKEN}
      JIRA_USER_EMAIL: ${JIRA_USER_EMAIL}
      JIRA_PROJECT_KEYS: ${JIRA_PROJECT_KEYS:-}
      JIRA_TOOLS: ${JIRA_TOOLS:-}
      MCP_TRANSPORT: http
      MCP_HOST: 0.0.0.0
      MCP_PORT: 8080
      MCP_AUTH_MODE: ${MCP_AUTH_MODE:-none}
      MCP_SERVER_TOKEN: ${MCP_SERVER_TOKEN:-}
    restart: unless-stopped

docker compose up -d                        # reads .env for JIRA_* / MCP_SERVER_TOKEN
curl http://127.0.0.1:8080/health

Kubernetes (example)

apiVersion: apps/v1
kind: Deployment
metadata: { name: jira-mcp }
spec:
  replicas: 2
  template:
    metadata: { labels: { app: jira-mcp } }
    spec:
      containers:
        - name: jira-mcp
          image: your-registry/jira-mcp-server:latest
          ports: [{ containerPort: 8080 }]
          envFrom: [{ secretRef: { name: jira-mcp-secrets } }]
          readinessProbe:
            httpGet: { path: /health, port: 8080 }
---
apiVersion: v1
kind: Service
metadata: { name: jira-mcp }
spec:
  selector: { app: jira-mcp }
  ports: [{ port: 8080, targetPort: 8080 }]

Troubleshooting

Diagnosing Jira auth quickly: run

jira-mcp-server --transport stdio
# and in a client, call jira_get_myself — it returns the Jira user the token resolves to.

Rate limiting: the client limiter blocks the calling task instead of erroring, so batch prompts just run a little slower. Jira's own limits are upstream of the token; space out CI loops and use max_results liberally.

Development

Add a new tool

1. Open src/jira_mcp_server/tools/issues.py (or the matching module).

2. Inside the existing register(registry) function add:

@registry.tool(name="my_new_tool", title="...", description="...")
async def my_new_tool(
    ctx: Context,
    param1: Annotated[str, Field(description="...")],
    optional: Annotated[int | None, Field(default=None, description="...")] = None,
) -> Any:
    """Docstring used as the default description."""
    client = get_client()
    try:
        data = await client.some_endpoint(param1)
        return dict_result(data, label="result")
    except Exception as exc:
        return error_result(exc)

3. Add the matching client method in src/jira_mcp_server/client.py.

4. Run the tests.

Add a new resource

In src/jira_mcp_server/tools/resources.py, inside register():

@registry.resource("jira://issue/{issue_key}/comments")
def comments_for_issue(issue_key: str) -> str:
    return json_dumps(get_client().get_comments_blocking_for_resource(issue_key))

Tests

pytest                                # full suite
pytest -m "not network"               # offline unit + integration tests
pytest tests/test_transport_http.py   # HTTP/SSE app tests

The suite uses pytest + pytest-asyncio; HTTP tests run against an in-process Starlette app via httpx.ASGITransport (no live network).

Style

ruff (lint + format) and mypy are configured in pyproject.toml:

ruff check src tests
ruff format --check src tests
mypy src

Commit messages: conventional-commit style (e.g. feat: add jira_export_issues). Changes land via PR; each PR must pass lint, type checks, and the test suite.

Building the jira-mcp-server.exe console script

There is no separate "build" step for the executable — on Windows it is created automatically when you install the project, from the [project.scripts] entry point in pyproject.toml:

[project.scripts]
jira-mcp-server = "jira_mcp_server.cli:app"

What the entry point produces

pip (via the setuptools backend) generates a small launcher:

• On Windows: jira-mcp-server.exe inside the Python environment's Scripts folder (e.g. D:\develop\Python312\Scripts\jira-mcp-server.exe, or .venv\Scripts\jira-mcp-server.exe when using a virtual env).

• On macOS/Linux: a jira-mcp-server shell script on PATH.

The launcher is a thin shim that imports jira_mcp_server.cli and calls app (a Typer command). All real logic lives in src/; the .exe is just a starter.

Build it from source (Windows)

# 1. Create and activate a virtual environment.
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 2. Install the project (editable keeps src/ live; plain install copies it).
#    Either is fine. "-e" means you can edit src/ and restart the MCP client
#    without reinstalling.
python -m pip install -e ".[dev]"      # editable, recommended for development
# python -m pip install .              # regular install, recommended for a fixed version

# 3. The .exe is now on PATH inside the venv (or the base Scripts dir).
jira-mcp-server --version              # -> jira-mcp-server 0.1.1

Verify

python -m jira_mcp_server --version   # same behavior as the exe
jira-mcp-server --version             # the generated launcher/exe

If jira-mcp-server is not found, ensure the environment's Scripts directory is on PATH (Python's installer usually adds it). To reinstall after deleting the launcher, re-run pip install -e ..

Editable vs. regular install

• pip install -e . ("editable") registers the launcher but points it back at your src/ tree. Edit source, restart the MCP client, and the change is picked up without reinstalling — the normal choice while developing.

• pip install . ("regular") copies the package into the environment's site-packages; the launcher runs that frozen copy. Use it for a fixed version you do not expect to edit.

Both commands produce the same jira-mcp-server.exe; only where the code lives differs.

Build without a virtual environment

If you installed Python globally and cannot or do not want a venv, run pip install -e . directly. The launcher then lands in the base interpreter's Scripts folder (e.g. D:\develop\Python312\Scripts\jira-mcp-server.exe), which must be on PATH for MCP clients to find the jira-mcp-server command.

Architecture / how to extend

src/jira_mcp_server/
├── cli.py            # typer CLI → transport selection
├── server.py         # create_server(): MCPServer + registration
├── config.py         # pydantic-settings (JIRA_* env), validated, lazy
├── safety.py         # credential masking / normalization
├── permissions.py    # JIRA_TOOLS allowlist: CRUD categories → tool sets
├── client.py         # JiraClient: httpx async, retry, pagination, scope
├── auth.py           # Basic / Bearer header construction
├── errors.py         # JiraError hierarchy + status mapping
├── formatters.py     # ADF ⇄ plain text
├── validators.py     # safe JQL building
├── rate_limiter.py   # token bucket
├── middleware.py     # HTTP auth / logging / CORS middleware + /health
├── transport/
│   ├── stdio.py      # stdio runner
│   ├── http.py       # SSE + Streamable HTTP apps (extends SDK app)
│   └── logging.py    # stderr/file logging, sensitive filter
└── tools/
    ├── core.py       # ToolRegistry, register_server, shared client
    ├── serde.py      # CallToolResult helpers
    ├── issues.py     # 14 issue tools
    ├── projects.py   # 3 project tools
    ├── sprints.py    # 4 board/sprint tools
    ├── users.py      # 2 user tools
    ├── attachments.py# 2 attachment tools
    ├── worklog.py    # 2 worklog tools
    ├── resources.py  # 4 MCP resources
    └── prompts.py    # 4 MCP prompts

Planned / extension points

• Webhook events (the transport layer is decoupled so an HTTP Webhook route can be added without touching the tools).

• Multi-Jira-instance support (the config layer is a single Settings object; a future MCP_INSTANCES could create one per instance).

• Per-tool granular Prompts / completion metadata.

Changelog

v0.1.1 (2026-08-06)

• Tool permission control (JIRA_TOOLS) — restrict which MCP tools are exposed via comma-separated CRUD keywords (read/create/update/ delete/write) or exact tool names. Disabled tools are not registered, so clients never see them; typos fail startup. See Tool permissions.

• Docs: 补充 基于源码安装（含 Windows PowerShell/CMD 命令）与本地生成 jira-mcp-server.exe 的完整说明；新增 Client token (HTTP 认证) 章节，说明 client-token 的生成、服务端与 客户端两侧的配置方式及旋转方法。

v0.1.0 (2026-08-06)

• Initial release.

Jira MCP Server is not affiliated with, endorsed by, or sponsored by Atlassian. "Jira" is a trademark of Atlassian Pty Ltd.