Jira MCP

A small local Model Context Protocol server for Jira Cloud. It provides four read tools by default and three deliberately guarded write tools when writes are enabled before launch.

Tools

Read-only tools:

• get_issue: retrieve one issue by key or numeric ID; description is opt-in and capped at 8,000 characters.

• search_issues: run JQL with a default page size of 20 and a hard maximum of 50.

• list_project_issues: construct bounded JQL from a project key and optional status or assignee filter.

• list_issue_transitions: list the workflow transitions currently available for an issue, including destination status and whether a transition screen is present.

Every tool returns structured content plus a concise text view. Jira-sourced text is explicitly marked as untrusted reference data.

Write tools, available only with JIRA_ENABLE_WRITES=true:

• create_issue: create one basic issue using project, issue type, summary, optional plain-text description, and optional labels.

• add_comment: add one plain-text comment to an issue.

• transition_issue: apply one approved workflow transition by transition ID, then read the issue back to verify its resulting status.

Write inputs are length-limited and converted to Jira Cloud's Atlassian Document Format where required. The write tools support standard fields only; they do not discover or guess required custom fields or transition-screen values.

Related MCP server: atlassian-mcp

Safety defaults

• Jira credentials are supplied through environment variables and are never committed.

• Jira text is returned as untrusted reference data, not as instructions.

• Descriptions are excluded by default and capped when explicitly requested.

• Write tools are absent unless the server starts with JIRA_ENABLE_WRITES=true.

• Write tools are marked destructive and non-idempotent for MCP hosts. Their descriptions require the host to show the exact proposed change and obtain human approval before calling them.

• The server never retries a write automatically. If a timeout or connection failure makes the result uncertain, check Jira before deciding whether to retry.

• Jira status is changed through workflow transitions, not by editing the status field. Call list_issue_transitions first, present the exact issue, transition, and destination status for approval, then pass the selected numeric transition ID to transition_issue.

Requirements

• Node.js 20 or newer

• A Jira Cloud site

• An Atlassian account email and API token for live use

Development

npm install
npm run verify

The verification command runs strict type-checking, a clean build, mocked Jira-client tests, in-memory MCP tests, and a compiled stdio subprocess test. Automated tests do not require Jira credentials or network access.

Configuration

Use .env.example only as a reference. Supply real values through your MCP host's local environment configuration:

JIRA_BASE_URL=https://your-site.atlassian.net
JIRA_EMAIL=your-atlassian-email@example.com
JIRA_API_TOKEN=your-local-api-token
JIRA_ENABLE_WRITES=false
NODE_EXTRA_CA_CERTS=/etc/ssl/cert.pem

Do not commit these values or paste the API token into chat. The base URL must be an HTTPS *.atlassian.net origin without a path, custom port, query string, or fragment.

Keep JIRA_ENABLE_WRITES=false for normal read-only use. To make write tools discoverable, set it to exactly true and restart the MCP server. Enabling the flag does not itself prove human approval; the MCP host remains responsible for approval of each exact change.

After running npm run build, an MCP host should launch:

node /absolute/path/to/jira-mcp/dist/index.js

The host must pass these environment variables to the process. NODE_EXTRA_CA_CERTS ensures a GUI-launched Node process uses macOS's maintained certificate bundle even when it does not inherit ~/.zshenv. Diagnostics go to stderr; stdout is reserved for the MCP protocol.

Pagination

Search tools return nextPageToken and hasMore. Pass the token into a subsequent call to retrieve the next Jira page. The server never downloads every page automatically.

Known boundaries

• Jira Cloud only; Jira Data Center is not supported.

• Basic authentication uses an Atlassian email and API token for this local single-user project.

• OAuth, remote HTTP hosting, custom fields, transition-screen fields, attachments, and bulk operations are outside the MVP.

• Issue creation works only where Jira accepts the standard fields exposed by this POC. Jira validation errors are returned without guessing missing custom-field values.

• Jira descriptions may contain instruction-like text. They remain untrusted data regardless of wording.

• This POC proves Jira-side MCP capabilities for a possible larger integration. It does not connect to Pronto or implement production synchronization, mapping, deduplication, or orchestration.