Jira MCP

A small local Model Context Protocol server for Jira Cloud. Version 0.1.0 is read-only and provides tools to retrieve an issue, search with JQL, and list issues in a project.

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.

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

Related MCP server: jira-mcp-server

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 not part of version 0.1.0, even if JIRA_ENABLE_WRITES=true is present.

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.

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, transitions, attachments, and bulk operations are outside the MVP.

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

Write tools will be considered only after the read-only review checkpoint passes.