jira-service-desk-mcp

MCP (Model Context Protocol) server for Jira Service Management (formerly Jira Service Desk).
Connects AI assistants — Claude Code, Claude Desktop, Cursor, and others — to your JSM instance via Anthropic's MCP.

Built on top of atlassian-python-api and inspired by mcp-atlassian.

Features

40 tools total. Write operations are gated by READ_ONLY_MODE.

Quick Start

Install from PyPI

pip install jira-service-desk-mcp

Or with uv:

uv pip install jira-service-desk-mcp

Or install from source:

pip install -e .

Configure

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Recommended shared format (same env shape as mcp-atlassian):

JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=<base64-encoded username:token>

Use a base64-encoded username:token string when you want one MCP config style that works across both mcp-atlassian and jira-service-desk-mcp for Atlassian Cloud. On non-Cloud/self-hosted Jira instances, JIRA_PERSONAL_TOKEN now defaults to Bearer/PAT handling to avoid misclassifying base64-looking PATs. If you intentionally need basic auth there, set JIRA_PERSONAL_TOKEN_MODE=basic.

Alternative: Atlassian Cloud (username + API token):

JIRA_URL=https://your-instance.atlassian.net
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-api-token

Generate an API token at https://id.atlassian.com/manage-profile/security/api-tokens.

Alternative: Server / Data Center (raw Personal Access Token):

JIRA_URL=https://jira.your-company.com
JIRA_PERSONAL_TOKEN=your-personal-access-token

The token can be either a raw PAT (bearer token), the full Bearer <token> header value, or a base64-encoded username:api_token string. The server strips Bearer automatically when present.

For non-Cloud/self-hosted Jira, JIRA_PERSONAL_TOKEN is treated as Bearer/PAT by default, even if it looks like base64. This avoids accidental fallback to Basic auth for PATs that happen to decode cleanly. If you need to force Basic auth from JIRA_PERSONAL_TOKEN, set:

JIRA_PERSONAL_TOKEN_MODE=basic

Note: JIRA_IS_CLOUD is auto-detected from the URL (.atlassian.net → Cloud). Set it explicitly only if the heuristic is wrong for your instance.

Run

stdio (default — for Claude Code, Claude Desktop, Cursor, etc.):

jira-service-desk-mcp

SSE (for remote/web clients):

jira-service-desk-mcp --transport sse --port 8000

Claude Code Integration

The fastest way to connect JSM to Claude Code:

claude mcp add jira-service-desk -- jira-service-desk-mcp

With environment variables inline:

claude mcp add jira-service-desk \
  -e JIRA_URL=https://jira.your-company.com \
  -e JIRA_PERSONAL_TOKEN=<base64-encoded username:token> \
  -- uvx jira-service-desk-mcp

To scope the server to your project only:

claude mcp add --scope project jira-service-desk \
  -e JIRA_URL=https://jira.your-company.com \
  -e JIRA_PERSONAL_TOKEN=<base64-encoded username:token> \
  -- uvx jira-service-desk-mcp

Verify it works:

claude mcp list

Shared MCP Config

Add the same shape to ~/.claude.json, project-level .mcp.json, claude_desktop_config.json, or .cursor/mcp.json:

{
  "mcpServers": {
    "mcp-atlassian": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-atlassian"],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "<base64-encoded username:token>"
      }
    },
    "jira-service-desk": {
      "type": "stdio",
      "command": "uvx",
      "args": ["jira-service-desk-mcp"],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "<base64-encoded username:token>"
      }
    }
  }
}

This mirrors the mcp-atlassian configuration style for Atlassian Cloud while still allowing jira-service-desk-mcp to distinguish Cloud basic-auth tokens from non-Cloud Bearer/PAT tokens.

Environment Variables

Available Tools

Service Desks

• get_service_desk_info — Application info
• list_service_desks — All accessible service desks
• get_service_desk — Service desk by ID

Request Types

• list_request_types — Request types for a desk
• get_request_type — Specific request type
• get_request_type_fields — Fields required for a request type

Customer Requests

• create_customer_request — Create a new request
• get_customer_request — Get request by key
• list_my_customer_requests — Your requests
• get_customer_request_status — Request status

Comments

• add_request_comment — Add public or internal comment
• list_request_comments — List comments on a request
• get_request_comment — Get comment by ID

Customers

• create_customer — Create customer account
• list_customers — List customers of a desk
• add_customers_to_service_desk — Add customers
• remove_customers_from_service_desk — Remove customers

Participants

• list_request_participants — List participants
• add_request_participants — Add participants
• remove_request_participants — Remove participants

Transitions

• list_customer_transitions — Available transitions
• perform_transition — Execute a transition

Organizations

• list_organizations — List organizations
• get_organization — Organization by ID
• create_organization — Create organization
• delete_organization — Delete organization
• add_organization_to_service_desk — Link org to desk
• remove_organization_from_service_desk — Unlink org
• list_users_in_organization — Users in org
• add_users_to_organization — Add users to org
• remove_users_from_organization — Remove users from org

Queues

• list_queues — Queues in a service desk
• list_issues_in_queue — Issues in a queue

SLA

• get_request_sla — SLA info for a request
• get_request_sla_by_id — Specific SLA metric

Approvals

• list_approvals — Approvals for a request
• get_approval — Approval by ID
• answer_approval — Approve or decline

Attachments

• upload_temporary_attachment — Upload temp file
• attach_file_to_request — Attach to request

Architecture

src/mcp_jira_service_desk/
├── __init__.py      # CLI entry point (click)
├── __main__.py      # python -m support
├── config.py        # Environment-based configuration
├── client.py        # ServiceDeskClient — wraps atlassian-python-api
├── formatting.py    # Human-readable formatting for API responses
└── server.py        # FastMCP server with all tool definitions

• config.py — reads JIRA_* env vars, determines auth type
• client.py — thin typed wrapper around atlassian.ServiceDesk, normalizes paginated responses
• formatting.py — converts raw API dicts into markdown for LLM consumption
• server.py — FastMCP instance with @mcp.tool() decorators for each operation

Development

git clone https://github.com/CzSadykov/jira-service-desk-mcp.git
cd jira-service-desk-mcp
pip install -e ".[dev]"
pytest

License

MIT