Jiraxmcp

npm version Publish to NPM License: MIT

jiraxmcp is an open-source Jira stdio MCP server built on top of jira.js, commander, and @modelcontextprotocol/sdk.

It lets MCP-compatible clients interact with Jira Cloud through issue, search, agile, comment, link, and attachment tools. It can also subscribe to inbound Jira webhook events through an MCP notification channel backed by a built-in HTTP server.

Highlights

• Exposes Jira Cloud as an MCP server over stdio.
• Uses the official jira.js client for Jira REST and Agile API access.
• Supports either JIRA_ACCESS_TOKEN or JIRA_EMAIL plus JIRA_API_TOKEN.
• Provides issue CRUD, search, field lookup, agile board and sprint tools, comments, changelogs, links, and attachment helpers.
• Can emit incoming Jira webhook events over an optional MCP notification channel.
• Starts a built-in Express webhook listener on /webhook when channel mode is enabled.

Requirements

• Node.js 24+
• Jira Cloud base URL exported as JIRA_HOST
• Either:
  • JIRA_EMAIL and JIRA_API_TOKEN, or
  • JIRA_ACCESS_TOKEN

Installation

Use it without installing globally:

npx jiraxmcp mcp

Or for local development:

npm install
npm run build
npm run dev -- mcp

Quick Start

1. Export your Jira credentials:

export JIRA_HOST="https://your-domain.atlassian.net"
export JIRA_EMAIL="[email protected]"
export JIRA_API_TOKEN="your-api-token"

Or with an access token:

export JIRA_HOST="https://your-domain.atlassian.net"
export JIRA_ACCESS_TOKEN="your-access-token"

2. Start the MCP server:

npx jiraxmcp mcp

3. If your MCP host supports notifications and you want inbound Jira webhook events, enable channels:

npx jiraxmcp mcp --channels

4. Configure Jira webhooks to point to your listener:

http://your-host:6543/webhook

JIRA_WEBHOOK_PORT overrides the default listener port 6543. JIRA_WEBHOOK_HOST controls the bind host and defaults to 127.0.0.1. If you configure a webhook secret in Jira admin webhooks, also set JIRA_WEBHOOK_SECRET so incoming X-Hub-Signature headers are verified before events are emitted.

The server uses stdio, so it is meant to be launched by an MCP client or wrapper rather than browsed directly in a terminal.

CLI Usage

MCP Server

npx jiraxmcp mcp

Starts the stdio MCP server for the configured Jira Cloud instance.

MCP Tools

The server currently exposes these tools:

• jira_get_issue
• jira_create_issue
• jira_update_issue
• jira_delete_issue
• jira_batch_create_issues
• jira_transition_issue
• jira_get_transitions
• jira_get_all_projects
• jira_get_project_issues
• jira_search_issues
• jira_search_fields
• jira_get_field_options
• jira_get_agile_boards
• jira_get_board_issues
• jira_get_sprints_from_board
• jira_get_sprint_issues
• jira_create_sprint
• jira_update_sprint
• jira_add_issues_to_sprint
• jira_add_comment
• jira_edit_comment
• jira_batch_get_changelogs
• jira_get_user_profile
• jira_search_users
• jira_get_link_types
• jira_create_issue_link
• jira_remove_issue_link
• jira_link_to_epic
• jira_create_remote_issue_link
• jira_download_attachments
• jira_get_issue_images

Push Channel

When started with --channels, the server:

• advertises the experimental MCP capability hooman/channel
• advertises hooman/user with path meta.user
• advertises hooman/session with path meta.session
• advertises hooman/thread with path meta.thread
• starts a built-in HTTP webhook listener on /webhook
• verifies X-Hub-Signature when JIRA_WEBHOOK_SECRET is set
• ignores duplicate webhook deliveries in memory using X-Atlassian-Webhook-Identifier
• emits notifications/hooman/channel for inbound Jira webhook events

Each notification includes:

• content: a JSON-encoded event payload
• meta.source: jira
• meta.user: the best available Jira actor identifier from the webhook payload
• meta.session: usually the issue key, otherwise the project key or webhook event name
• meta.thread: omitted for Jira webhook events

The JSON-decoded content payload includes:

• source
• self
• event
• timestamp
• payload
• issue: an object with optional key
• project: an object with optional key
• user: a best-effort object with id, name, and email

Environment

jiraxmcp reads environment variables from the shell and from .env automatically.

Supported variables:

• JIRA_HOST
• JIRA_EMAIL
• JIRA_API_TOKEN
• JIRA_ACCESS_TOKEN
• JIRA_WEBHOOK_PORT
• JIRA_WEBHOOK_HOST
• JIRA_WEBHOOK_SECRET

If JIRA_WEBHOOK_PORT is not set, the webhook listener uses 6543. JIRA_WEBHOOK_HOST defaults to 127.0.0.1; set it to 0.0.0.0 if you need Jira to reach the listener from another machine. JIRA_WEBHOOK_SECRET is optional, but when set the webhook endpoint only accepts deliveries whose X-Hub-Signature matches the raw request body.

Local Data

jiraxmcp stores local state under ~/.jiraxmcp/.

Downloaded issue attachments are saved under attachments/ within that data directory.

License

MIT. See LICENSE.