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

Related MCP server: Jira MCP Server

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

Configuration

The CLI accepts these optional environment variables:

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.