jiradatacenter-mcp

MCP server for Jira Data Center / Server (self-hosted Jira, REST API v2) — exposes core work-item project-management operations (platform + Agile) as MCP tools.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own site URL and Basic Auth credentials via headers, used only for the lifetime of that single request.

• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.

• Entry points: POST /mcp (MCP protocol) and GET /health (health check).

• Default port: 8080 (configurable via MCP_HTTP_PORT).

Related MCP server: Work Integrations MCP

Scope

15 tools, trimmed down from a prior 29-tool build (2026-08-07). The 15 kept tools focus on core issue/search/project/user/agile-sprint operations — full issue CRUD + comments + sub-tasks, JQL search, project lookups, user lookups, and read-only agile board/sprint operations. Dropped in this trim: the niche metadata-lookup categories (issuetype, priority, jql autocomplete, customfields) and the less-common bulk/sync-oriented tools (version project-version management, worklog sync-since-timestamp endpoints), plus 2 of the 5 agile tools (jira_agile_get_board, jira_agile_get_sprint — single- entity lookups that overlapped with the kept list-oriented board/sprint tools).

Everything else — customfields, issuetype, jql, priority, version, worklog (6 whole modules), plus jira_agile_get_board and jira_agile_get_sprint from agile.py — was removed from this build.

The original 214-tool full-WADL build was trimmed to 29 tools on 2026-08-04. MSPbots' own stored integration config for this vendor is a pre-generic-framework (legacy) integration — its 17 configured endpoint entries return an entirely empty apiConfig (real endpoint logic lives in backend Java code, not the generic config API), so there's no per-endpoint method/path to reverse-engineer directly. The 17 endpoint names were used as the category guide instead (Issue Search, Worklog, subtasks, User, request/Issue Comment, Project (Version), Board Sprint, Issuetype, Customfield, Priority, AutoCompleteData — "Queues"/"Queues Issue" map to Jira Service Desk and "Tempo Worklog" to the third-party Tempo plugin, neither of which this REST-v2-platform-+-Agile-only server implements, so those three are not covered), then for each matched category kept the one or two operations that fit that name plus minimal same-category CRUD, capped at 30 total:

Everything else from the original 214-tool build — attachment, comment (the standalone properties-only category; real comment CRUD lives in issue), component, customfieldoption, dashboard, field, filter, group, groups, groupuserpicker, issuelink(Type), mypermissions, mypreferences, myself, permissions, projectcategory, projectvalidate, resolution, role, securitylevel, serverinfo, status, statuscategory (24 categories, ~184 tools) — was removed as unused by MSPbots and out of scope for this server's purpose.

Original sourcing (for context on where the removed categories came from, and where to look if one needs to be re-added):

• Platform API: parsed from Atlassian's official machine-readable WADL spec for Jira 9.4.0 (https://docs.atlassian.com/software/jira/docs/api/REST/9.4.0/jira-rest-plugin.wadl).

• Agile API: manually curated from Atlassian's HTML docs at https://docs.atlassian.com/jira-software/REST/9.4.0/ — no WADL is published for this API.

Authentication

Jira Data Center/Server uses HTTP Basic Authentication (Authorization: Basic base64(username:password)) — confirmed against the credentials MSPbots stores for this integration (its token field is literally base64(username:password), not a separate secret). This server builds that header itself from the raw username/password on every request; the site's base URL is also per-tenant (each MSPbots tenant may point at a different Jira instance), so it is supplied as a header too, not a fixed environment variable.

HEADER 授权参数说明

Missing any header returns 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Jira-Site, X-Jira-Username and X-Jira-Password headers",
  "required_headers": ["X-Jira-Site", "X-Jira-Username", "X-Jira-Password"],
  "optional_headers": []
}

Environment Variables

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)

• GET /health — health check, returns {"status": "ok", "service": "jiradatacenter-mcp", "transport": "http"}

Tool List

Tool names are jira_<category>_<operationId>, derived from the WADL <method id="..."> / manually-curated Agile operation_id. body parameters are accepted as a generic dict — see the Jira Server REST API reference (linked below) for each resource's exact JSON schema.

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Jira-Site: jira.example.com" \
  -H "X-Jira-Username: api_user" \
  -H "X-Jira-Password: Sample_Passw0rd!" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "jira_myself_get_user",
      "arguments": {}
    }
  }'

Self-test limitation (2026-07-29): the provided test account (jira.mspbots.ai, user mspbots_api) could not be live-verified from this build environment — direct requests to jira.mspbots.ai (both through this server and via plain curl) consistently return a generic 404 page not found, and DNS resolves the host to a sandbox-local address. This is consistent with MSPbots' internal servers being RDP-only / network-isolated from this environment, not a bug in the server itself. What was verified end-to-end from this environment: the MCP protocol handshake, tools/list returning all 214 registered tools, the 401 credential-gating behavior, and that a live call reaches the constructed URL and receives an HTTP response (proving the request/auth-header plumbing works) — only the vendor-side reachability of the real instance could not be confirmed. A real functional self-test against jira.mspbots.ai should be run from a network that can actually reach it (e.g. via RDP to an MSPbots-internal host).

API Reference

• Platform API WADL: https://docs.atlassian.com/software/jira/docs/api/REST/9.4.0/jira-rest-plugin.wadl

• Platform API docs: https://docs.atlassian.com/software/jira/docs/api/REST/9.4.0/

• Agile API docs: https://docs.atlassian.com/jira-software/REST/9.4.0/

Known Gaps

• Trimmed from 29 to 15 tools on 2026-08-07, focused on core issue/search/project/user/agile-sprint operations. Dropped: the niche metadata-lookup categories (issuetype, priority, jql autocomplete, customfields) and the less-common bulk/sync tools (version project-version management, worklog sync-since-timestamp endpoints), plus 2 of 5 agile tools (jira_agile_get_board, jira_agile_get_sprint). See the Scope section above for the exact category→tool mapping.

• Trimmed from 214 to 29 tools on 2026-08-04 (dropped the one write op, jira_agile_create_sprint, that wasn't part of MSPbots' read-only "Board Sprint" usage, to land under 30). The original build expanded beyond MSPbots' 17 named endpoints to full core work-item categories per an earlier scope decision. A later scope decision cut this back down to what those 17 endpoint names actually map to, plus minimal same-category CRUD — see the Scope section above for the exact category→tool mapping and the full list of removed categories (24 categories, ~184 tools). If a future need requires one of the removed categories, Atlassian's WADL spec (linked above) still documents its exact operations and they can be re-added the same way the kept tools were generated.

• "Queues"/"Queues Issue" (Jira Service Desk) and "Tempo Worklog" (third-party plugin) are not covered at all — neither is part of the platform-v2-REST-API-plus-Agile-API surface this server implements, so 2 of MSPbots' 17 configured endpoint names have no corresponding tool here even after the trim.

• body parameters are untyped (dict) rather than fully modeled — the Jira REST API reference documents the exact schema per resource, but reproducing all of them as typed Python parameters was out of scope for a mechanically-generated server.

• Live functional self-test could not be completed from this build environment due to jira.mspbots.ai being unreachable here (see 测试示例 above for exactly what was and wasn't verified).

• Several kept operations mutate or delete real data (jira_issue_delete_issue, jira_issue_create_issue, jira_issue_edit_issue, jira_issue_add_comment, etc.) — treat any DELETE/destructive POST/PUT tool as irreversible against a production Jira instance and confirm with a human before invoking.