Skip to main content
Glama
jira-service-desk-mcp

jira-service-desk-mcp

by CzSadykov

jira-service-desk-mcp

PyPI Python License: MIT

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

Category

Tools

Service Desks

List desks, get desk by ID, app info

Request Types

List types, get type details, get required fields

Customer Requests

Create, get, list my requests, get status

Comments

Add public/internal comments, list, get by ID

Customers

Create customer, list, add/remove from desk

Participants

List, add, remove request participants

Transitions

List available transitions, perform transition

Organizations

CRUD organizations, manage users, link to desks

Queues

List queues, list issues in queue

SLA

Get SLA info per request, by metric ID

Approvals

List approvals, get by ID, approve/decline

Attachments

Upload temp file, attach to request

40 tools total. Write operations are gated by READ_ONLY_MODE.

Related MCP server: Jira MCP Server

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

Variable

Required

Description

JIRA_URL

Yes

Jira instance URL

JIRA_USERNAME

Cloud

Email for Atlassian Cloud

JIRA_API_TOKEN

Cloud

API token for Cloud auth

JIRA_PERSONAL_TOKEN

Recommended

Raw PAT or base64-encoded username:token

JIRA_PERSONAL_TOKEN_MODE

No

auto (default), pat, or basic override for JIRA_PERSONAL_TOKEN

JIRA_PASSWORD

—

Basic auth password (not recommended)

JIRA_IS_CLOUD

No

Auto-detected from URL; set explicitly to override

JIRA_SSL_VERIFY

No

true (default) or false

READ_ONLY_MODE

No

true to disable all write operations

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

Available Tools

40 tools
add_customers_to_service_deskA

Grant one or more users access to a service desk as customers.

Provide usernames for Server/Data Center or account_ids for Cloud.

Args: service_desk_id: The numeric ID of the service desk. usernames: (Optional) Comma-separated usernames (Server/DC). account_ids: (Optional) Comma-separated Atlassian account IDs (Cloud).

Inputs: service_desk_id (required), usernames, account_ids. Returns: result

add_organization_to_service_deskB

Link an organization to a service desk so its members can raise requests.

Args: service_desk_id: The numeric ID of the service desk. organization_id: The numeric organization ID.

Inputs: service_desk_id (required), organization_id (required). Returns: result

add_request_commentA

Add a comment to a customer request.

Set public=true for customer-visible replies or public=false for internal agent notes that the customer cannot see.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. body: The comment text (plain text or Jira wiki markup). public: true — visible to customer; false — internal agent note.

Inputs: issue_id_or_key (required), body (required), public. Returns: result

add_request_participantsB

Add participants to a customer request so they receive updates.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. usernames: (Optional) Comma-separated usernames (Server/DC). account_ids: (Optional) Comma-separated Atlassian account IDs (Cloud).

Inputs: issue_id_or_key (required), usernames, account_ids. Returns: result

add_users_to_organizationA

Add users to an organization.

Provide usernames for Server/Data Center or account_ids for Cloud.

Args: organization_id: The numeric organization ID. usernames: (Optional) Comma-separated usernames (Server/DC). account_ids: (Optional) Comma-separated Atlassian account IDs (Cloud).

Inputs: organization_id (required), usernames, account_ids. Returns: result

answer_approvalA

Approve or decline an approval request.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. approval_id: The numeric approval ID. decision: "approve" or "decline".

Inputs: issue_id_or_key (required), approval_id (required), decision (required). Returns: result

attach_file_to_requestA

Attach a previously uploaded temporary file to a customer request.

Call upload_temporary_attachment first to obtain the temporary ID.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. temp_attachment_id: The temporary attachment ID returned by upload_temporary_attachment. public: true — visible to customers; false — internal only. comment: (Optional) Comment to accompany the attachment.

Inputs: issue_id_or_key (required), temp_attachment_id (required), public, comment. Returns: result

create_customerA

Create a new customer account in the JSM instance (experimental API).

The customer will be able to raise requests through the customer portal.

Args: full_name: The customer's display name (e.g. "Jane Doe"). email: The customer's email address.

Inputs: full_name (required), email (required). Returns: result

create_customer_requestA

Create a new customer request (ticket) in a service desk.

Tip: call get_request_type_fields first to discover required field IDs and valid values for the chosen request type.

Args: service_desk_id: The numeric ID of the service desk (e.g. "1"). request_type_id: The numeric ID of the request type (e.g. "10"). values_json: JSON object with field values. Example: {"summary": "VPN not working", "description": "Cannot connect since morning"} raise_on_behalf_of: (Optional) Account ID (Cloud) or username (Server/DC) to raise the request on behalf of another user. request_participants: (Optional) Comma-separated account IDs or usernames to add as request participants.

Inputs: service_desk_id (required), request_type_id (required), values_json (required), raise_on_behalf_of, +1 more. Returns: result

create_organizationB

Create a new customer organization.

Args: name: The display name for the new organization.

Inputs: name (required). Returns: result

delete_organizationB

Permanently delete an organization and remove all its member associations.

Args: organization_id: The numeric organization ID.

Inputs: organization_id (required). Returns: result

get_approvalA

Get details of a specific approval including approver decisions.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. approval_id: The numeric approval ID.

Inputs: issue_id_or_key (required), approval_id (required). Returns: result

get_customer_requestA

Get full details of a customer request including status, reporter, and field values.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID.

Inputs: issue_id_or_key (required). Returns: result

get_customer_request_statusA

Get the current status and status category of a customer request.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID.

Inputs: issue_id_or_key (required). Returns: result

get_organizationB

Get details of a specific organization by its ID.

Args: organization_id: The numeric organization ID.

Inputs: organization_id (required). Returns: result

get_request_commentA

Get a single comment by its ID.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. comment_id: The numeric comment ID.

Inputs: issue_id_or_key (required), comment_id (required). Returns: result

get_request_slaA

Get SLA (Service Level Agreement) metrics for a customer request.

Returns remaining time, breach status, and goal durations for every SLA metric configured on the request.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. start: Pagination offset (0-based). limit: Maximum number of results (default 50).

Inputs: issue_id_or_key (required), start, limit. Returns: result

get_request_sla_by_idA

Get a specific SLA metric by its ID for a customer request.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. sla_id: The SLA metric ID.

Inputs: issue_id_or_key (required), sla_id (required). Returns: result

get_request_typeA

Get details of a specific request type (name, description, help text).

Args: service_desk_id: The numeric ID of the service desk (e.g. "1"). request_type_id: The numeric ID of the request type (e.g. "10").

Inputs: service_desk_id (required), request_type_id (required). Returns: result

get_request_type_fieldsA

Get the fields required to create a request of this type.

Always call this before create_customer_request to learn which fields are required, their IDs, and valid values.

Args: service_desk_id: The numeric ID of the service desk (e.g. "1"). request_type_id: The numeric ID of the request type (e.g. "10").

Inputs: service_desk_id (required), request_type_id (required). Returns: result

get_service_deskA

Get details of a specific service desk by its numeric ID.

Use list_service_desks first to find the ID.

Args: service_desk_id: The numeric ID of the service desk (e.g. "1").

Inputs: service_desk_id (required). Returns: result

get_service_desk_infoA

Get information about the Jira Service Management application.

Returns version and other runtime details of the JSM instance. Use this to verify connectivity and check the installed JSM version.

Inputs: no named parameters. Returns: result

list_approvalsA

List pending and completed approvals for a customer request.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. start: Pagination offset (0-based). limit: Maximum number of results (default 50).

Inputs: issue_id_or_key (required), start, limit. Returns: result

list_customersA

List customers who have access to a service desk.

Optionally filter by name or email substring.

Args: service_desk_id: The numeric ID of the service desk (e.g. "1"). query: (Optional) Filter string — matches against display name and email address. start: Pagination offset (0-based). limit: Maximum number of results (default 50).

Inputs: service_desk_id (required), query, start, limit. Returns: result

list_customer_transitionsA

List transitions available for a customer request in its current status.

Use the returned transition IDs with perform_transition.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID.

Inputs: issue_id_or_key (required). Returns: result

list_issues_in_queueA

List customer requests currently sitting in a specific queue.

Use list_queues first to discover queue IDs.

Args: service_desk_id: The numeric ID of the service desk. queue_id: The numeric queue ID. start: Pagination offset (0-based). limit: Maximum number of results (default 50).

Inputs: service_desk_id (required), queue_id (required), start, limit. Returns: result

list_my_customer_requestsA

List customer requests raised by or involving the current user.

Returns requests where the authenticated user is the reporter or a participant. Useful to see "my open tickets" at a glance.

Inputs: no named parameters. Returns: result

list_organizationsA

List organizations, optionally scoped to a specific service desk.

Organizations group customers for easier access management.

Args: service_desk_id: (Optional) Limit results to organizations linked to this service desk. start: Pagination offset (0-based). limit: Maximum number of results (default 50).

Inputs: service_desk_id, start, limit. Returns: result

list_queuesA

List agent queues defined in a service desk.

Queues are saved JQL filters that agents use to triage requests (e.g. "All open", "Unassigned", "SLA breached").

Args: service_desk_id: The numeric ID of the service desk (e.g. "1"). include_count: Set true to include the number of issues per queue. start: Pagination offset (0-based). limit: Maximum number of results (default 50).

Inputs: service_desk_id (required), include_count, start, limit. Returns: result

list_request_commentsA

List comments on a customer request with filtering by visibility.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. public: Include public (customer-visible) comments. internal: Include internal (agent-only) comments. start: Pagination offset (0-based). limit: Maximum number of comments to return (default 50).

Inputs: issue_id_or_key (required), public, internal, start, +1 more. Returns: result

list_request_participantsA

List users who participate in (watch) a customer request.

Participants receive notifications about request updates.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. start: Pagination offset (0-based). limit: Maximum number of results (default 50).

Inputs: issue_id_or_key (required), start, limit. Returns: result

list_request_typesA

List all request types available in a service desk.

Each request type defines a form that customers fill in when raising a request (e.g. "Report a bug", "Request access"). Use this to discover which request types are available before creating a customer request.

Args: service_desk_id: The numeric ID of the service desk (e.g. "1").

Inputs: service_desk_id (required). Returns: result

list_service_desksA

List all service desks accessible to the current user.

Returns IDs, project keys and names of every service desk the authenticated user can see. Use this as a starting point to discover available service desks before querying request types, queues, etc.

Inputs: no named parameters. Returns: result

list_users_in_organizationA

List users who belong to an organization.

Args: organization_id: The numeric organization ID. start: Pagination offset (0-based). limit: Maximum number of results (default 50).

Inputs: organization_id (required), start, limit. Returns: result

perform_transitionA

Perform a workflow transition on a customer request (e.g. resolve, close).

Call list_customer_transitions first to discover available transition IDs.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. transition_id: The numeric transition ID. comment: (Optional) Comment to add along with the transition.

Inputs: issue_id_or_key (required), transition_id (required), comment. Returns: result

remove_customers_from_service_deskA

Revoke customer access from a service desk.

Provide usernames for Server/Data Center or account_ids for Cloud.

Args: service_desk_id: The numeric ID of the service desk. usernames: (Optional) Comma-separated usernames (Server/DC). account_ids: (Optional) Comma-separated Atlassian account IDs (Cloud).

Inputs: service_desk_id (required), usernames, account_ids. Returns: result

remove_organization_from_service_deskB

Unlink an organization from a service desk.

Args: service_desk_id: The numeric ID of the service desk. organization_id: The numeric organization ID.

Inputs: service_desk_id (required), organization_id (required). Returns: result

remove_request_participantsA

Remove participants from a customer request.

Args: issue_id_or_key: The issue key (e.g. "X000") or numeric issue ID. usernames: (Optional) Comma-separated usernames (Server/DC). account_ids: (Optional) Comma-separated Atlassian account IDs (Cloud).

Inputs: issue_id_or_key (required), usernames, account_ids. Returns: result

remove_users_from_organizationA

Remove users from an organization.

Provide usernames for Server/Data Center or account_ids for Cloud.

Args: organization_id: The numeric organization ID. usernames: (Optional) Comma-separated usernames (Server/DC). account_ids: (Optional) Comma-separated Atlassian account IDs (Cloud).

Inputs: organization_id (required), usernames, account_ids. Returns: result

upload_temporary_attachmentA

Upload a file as a temporary attachment.

The returned temporary attachment ID must then be passed to attach_file_to_request to permanently attach it to a request.

Args: service_desk_id: The numeric ID of the service desk. filename: Absolute path to the file on the server filesystem.

Inputs: service_desk_id (required), filename (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 40 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action (e.g., add vs remove, customer vs organization), and even similar resources like comments have separate create/get/list tools. There is no confusion between tool purposes.

    Naming Consistency5/5

    Tool names consistently follow the verb_noun pattern in snake_case (e.g., list_service_desks, add_customers_to_service_desk). Minor deviations like get_service_desk_info are rare and do not break the pattern.

    Tool Count4/5

    40 tools cover a broad domain (desks, organizations, customers, requests, comments, approvals, queues, transitions, attachments). While slightly heavy, each tool serves a distinct purpose and the count is justified for the complexity of Jira Service Management.

    Completeness3/5

    Core CRUD and lifecycle operations are present for requests, comments, attachments, and organizations, but notable gaps exist: no update/delete for customers, no update for organizations, and no direct tool to update request fields (only transitions).

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with Jira Cloud and Server/Data Center deployments for issue management, project tracking, and workflow automation. Supports multiple authentication methods including API tokens, OAuth 2.0, and personal access tokens.
      MIT