jira-service-desk-mcp
Allows interaction with Jira Service Management, enabling AI assistants to manage service desks, requests, comments, customers, organizations, approvals, attachments, and perform transitions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@jira-service-desk-mcp get details of request IT-123"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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-mcpOr with uv:
uv pip install jira-service-desk-mcpOr install from source:
pip install -e .Configure
Copy .env.example to .env and fill in your credentials:
cp .env.example .envRecommended 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-tokenGenerate 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-tokenThe 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=basicNote:
JIRA_IS_CLOUDis 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-mcpSSE (for remote/web clients):
jira-service-desk-mcp --transport sse --port 8000Claude Code Integration
The fastest way to connect JSM to Claude Code:
claude mcp add jira-service-desk -- jira-service-desk-mcpWith 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-mcpTo 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-mcpVerify it works:
claude mcp listShared 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 |
| Yes | Jira instance URL |
| Cloud | Email for Atlassian Cloud |
| Cloud | API token for Cloud auth |
| Recommended | Raw PAT or base64-encoded |
| No |
|
| — | Basic auth password (not recommended) |
| No | Auto-detected from URL; set explicitly to override |
| No |
|
| No |
|
Available Tools
Service Desks
get_service_desk_info— Application infolist_service_desks— All accessible service desksget_service_desk— Service desk by ID
Request Types
list_request_types— Request types for a deskget_request_type— Specific request typeget_request_type_fields— Fields required for a request type
Customer Requests
create_customer_request— Create a new requestget_customer_request— Get request by keylist_my_customer_requests— Your requestsget_customer_request_status— Request status
Comments
add_request_comment— Add public or internal commentlist_request_comments— List comments on a requestget_request_comment— Get comment by ID
Customers
create_customer— Create customer accountlist_customers— List customers of a deskadd_customers_to_service_desk— Add customersremove_customers_from_service_desk— Remove customers
Participants
list_request_participants— List participantsadd_request_participants— Add participantsremove_request_participants— Remove participants
Transitions
list_customer_transitions— Available transitionsperform_transition— Execute a transition
Organizations
list_organizations— List organizationsget_organization— Organization by IDcreate_organization— Create organizationdelete_organization— Delete organizationadd_organization_to_service_desk— Link org to deskremove_organization_from_service_desk— Unlink orglist_users_in_organization— Users in orgadd_users_to_organization— Add users to orgremove_users_from_organization— Remove users from org
Queues
list_queues— Queues in a service desklist_issues_in_queue— Issues in a queue
SLA
get_request_sla— SLA info for a requestget_request_sla_by_id— Specific SLA metric
Approvals
list_approvals— Approvals for a requestget_approval— Approval by IDanswer_approval— Approve or decline
Attachments
upload_temporary_attachment— Upload temp fileattach_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 definitionsconfig.py — reads
JIRA_*env vars, determines auth typeclient.py — thin typed wrapper around
atlassian.ServiceDesk, normalizes paginated responsesformatting.py — converts raw API dicts into markdown for LLM consumption
server.py —
FastMCPinstance 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]"
pytestLicense
MIT
Available Tools
40 toolsadd_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
Scored across 40 tools
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.
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.
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.
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
Related MCP Connectors
Connect to Atlassian Jira, Confluence, Loom, and more to search, create, and manage your work.
Connect Claude, ChatGPT or any AI assistant to Zendesk tickets, CSAT, macros and Help Center.
Connect assistants to your workspace knowledge, skills, and work tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseAqualityNot gradedmaintenanceEnables AI assistants to interact with Atlassian Jira Cloud, allowing users to manage projects, issues, comments, and workflows through natural language commands.61,667 npm3-
- AlicenseAqualityDmaintenanceEnables AI agents to interact with Jira Cloud, including listing boards and issues, adding comments, and searching users.72MIT
- AlicenseCqualityDmaintenanceEnables AI assistants to manage Jira Cloud projects, issues, sprints, and more through a curated set of 62 tools covering the full lifecycle of stories, epics, bugs, and sprints.62GPL 3.0