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

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
update_comment	Replace an existing comment
get_attachments	List issue attachments and referenced media IDs
read_attachment	Read a bounded attachment; images are returned inline
get_transitions	List available status transitions
transition_issue	Transition an issue, optionally with a comment

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
JIRA_MCP_DATA_DIR	~/.jira-mcp	Config directory; primarily useful for tests/isolated runs

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.