Jira MCP

A local Model Context Protocol (MCP) server for Jira Cloud. It lets AI clients such as Codex and Claude search issues, inspect descriptions and comments, create or update issues, add rich comments, transition statuses, and read attachments.

Jira access uses an Atlassian account email and API token. Credentials stay on your machine in ~/.jira-mcp/sites.json; the server binds to 127.0.0.1 by default.

Features

• Streamable HTTP MCP endpoint with legacy SSE compatibility
• Local Web UI for configuring multiple Jira Cloud sites
• JQL search using Jira Cloud's enhanced /rest/api/3/search/jql API
• Issue creation, updates, comments, rich ADF comments, and transitions
• Attachment discovery and bounded inline image downloads
• Tool and client activity log
• Write-only API tokens in the Web UI/API
• User-only config directory and file permissions
• Local MCP OAuth compatibility endpoints for clients that require discovery

Requirements

• Node.js 22.14 or newer
• A Jira Cloud site
• An Atlassian account email and API token from Atlassian account security
• Optional: Microsoft markitdown for the attachment_to_markdown tool

Optional: markitdown

attachment_to_markdown is the one tool that shells out to an external program — markitdown, a Python tool. Install it either way:

pip install "markitdown[all]"   # puts "markitdown" on PATH
# or install uv, and "uvx markitdown" is fetched on demand

Already have it in a virtualenv? Point at it directly instead:

JIRA_MARKITDOWN_CMD="/opt/venv/bin/markitdown"

If none of these are present, attachment_to_markdown returns an error naming each command it tried and how to install it. Nothing else is affected — the server starts normally and every other tool, including download_attachment, works with no Python installed.

Installation

Run with npx

npx --yes @yunusemregul/jira-mcp@latest

Install globally

npm install --global @yunusemregul/jira-mcp
jira-mcp

The Web UI opens at http://127.0.0.1:18433. Add a Jira site, email, and API token there.

Options:
  -p, --port    Port to listen on (default: 18433, env: PORT)
      --host    Host to bind (default: 127.0.0.1, env: HOST)
  -v, --version Print version
  -h, --help    Show help

Connect an MCP client

Codex

codex mcp add jira-mcp --url http://127.0.0.1:18433/mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.jira-mcp]
url = "http://127.0.0.1:18433/mcp"

Claude Code

claude mcp add --transport sse jira-mcp http://127.0.0.1:18433/mcp/sse

Other Streamable HTTP clients

{
  "mcpServers": {
    "jira-mcp": {
      "url": "http://127.0.0.1:18433/mcp"
    }
  }
}

Some MCP clients require OAuth discovery even for a local server. Jira MCP exposes the same auto-approve compatibility endpoints as hac-mcp. They do not authenticate or authorize Jira access; the loopback bind is the security boundary.

Available tools

| Tool | Description | |---|---| | list_sites | List configured Jira sites without exposing credentials | | get_projects | List or filter accessible Jira projects | | search_issues | Search issues with JQL and token-based pagination | | get_issue | Read issue details, comments, custom text fields, and attachments | | create_issue | Create an issue | | update_issue | Update summary, description, priority, assignee, or labels | | add_comment | Add a plain-text comment | | add_comment_rich | Add an Atlassian Document Format comment | | get_comments | Read comments | | pull_comment | Save a comment's ADF to a local file for editing | | update_comment | Replace an existing comment, from an edited file or inline content | | get_attachments | List issue attachments and referenced media IDs | | read_attachment | Read a bounded attachment; images are returned inline | | download_attachment | Download an attachment to a local file and return its path for direct parsing | | attachment_to_markdown | Convert an attachment (xlsx, docx, pptx, PDF, HTML, CSV…) to Markdown via Microsoft markitdown | | upload_attachment | Upload local files (screenshots, logs, documents) as issue attachments | | get_transitions | List available status transitions | | transition_issue | Transition an issue, optionally with a comment |

Editing long comments

Resending a whole ADF document on every small change is slow and error-prone. Instead, work on a file:

1. pull_comment writes the comment's ADF to ~/.jira-mcp/drafts/<site>/<KEY>-<commentId>.json, pretty-printed so a single block can be edited on its own.
2. Edit only the part you want to change in that file.
3. update_comment({ file }) pushes it back. The site, issue key and comment ID are remembered next to the file, so they can be omitted.

The pull records the comment's updated timestamp. If somebody else edited the comment in the meantime, the push is rejected rather than silently overwriting their change; pull again and redo the edit, or pass force: true. add_comment_rich also saves what it posted, so a freshly created comment can be edited the same way without pulling first.

Configuration

The CLI accepts these optional environment variables:

| Variable | Default | Purpose | |---|---:|---| | HOST | 127.0.0.1 | HTTP bind host | | PORT | 18433 | HTTP port | | JIRA_REQUEST_TIMEOUT_MS | 30000 | Jira HTTP request timeout | | JIRA_MAX_ATTACHMENT_BYTES | 20971520 | Maximum attachment download size (applies to read_attachment and download_attachment) | | JIRA_MCP_DATA_DIR | ~/.jira-mcp | Config directory; primarily useful for tests/isolated runs | | JIRA_MARKITDOWN_CMD | markitdown (falls back to uvx markitdown) | Command used by attachment_to_markdown | | JIRA_MARKITDOWN_TIMEOUT_MS | 120000 | attachment_to_markdown conversion timeout | | JIRA_MARKITDOWN_MAX_CHARS | 200000 | Max Markdown characters returned by attachment_to_markdown |

Release Notes

v1.3.1 - Web UI shows the running server version next to the "Jira MCP" title, setup guide, and tools modal.

See CHANGELOG.md for the full version history.

Security

• Keep the default loopback bind. Setting HOST=0.0.0.0 exposes an unauthenticated local MCP service and Web UI; only do this behind a trusted authenticated reverse proxy.
• API tokens are stored locally in plaintext because the server must use them. The config directory is forced to mode 0700 and sites.json to 0600 on POSIX systems.
• API responses never return saved tokens. When editing a site, leave the token field blank to retain the existing token.
• Jira site URLs must use HTTPS and cannot embed credentials.
• The local OAuth compatibility endpoints auto-approve clients and are not a security mechanism.
• Attachment downloads default to a 20 MiB limit.

See SECURITY.md for reporting vulnerabilities.

Development

npm ci
npm run verify
npm start

npm run verify runs ESLint and the Node test suite. npm publish runs the same checks automatically through prepublishOnly.

Publishing

The npm package name is @yunusemregul/jira-mcp. The first publish must be performed interactively after enabling npm 2FA:

npm login
npm run verify
npm publish --access public

After the package exists, configure npm Trusted Publishing for .github/workflows/publish.yml. Subsequent v<package-version> tags publish from GitHub Actions using OIDC and npm provenance without a long-lived write token.

License

MIT License with the Commons Clause condition. See LICENSE.