Jira MCP Server

A Model Context Protocol (MCP) server for Jira — issue search, creation, updates, comments, status transitions, and project listing. Purpose-built for security incident management and SOC workflows.

Quick Start

Claude Desktop (stdio)

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@tocharianou/jira-mcp"],
      "env": {
        "JIRA_HOST": "https://yourorg.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_TOKEN": "<your-api-token>"
      }
    }
  }
}

Get your Jira API token at id.atlassian.com/manage-profile/security/api-tokens.

HTTP / Streamable mode

MCP_TRANSPORT=http MCP_HTTP_PORT=3002 JIRA_HOST=https://yourorg.atlassian.net JIRA_EMAIL=you@company.com JIRA_TOKEN=<token> npx @tocharianou/jira-mcp

Then point your MCP client at http://localhost:3002/mcp.

Features

• Issue search — JQL-powered queries for incidents, vulnerabilities, and tasks
• Issue management — create, update, comment, and transition issues
• Incident tracking — open security tickets directly from investigation findings
• Project discovery — list all accessible Jira projects
• Token limiting — built-in MAX_TOKEN_CALL guard prevents context overflow

Configuration

Environment variable	Required	Description
JIRA_HOST	✓	Jira Cloud: https://yourorg.atlassian.net / Server: https://jira.company.com
JIRA_EMAIL	✓*	Atlassian account email (Cloud only; leave empty for Server/DC)
JIRA_TOKEN	✓	API token (Cloud) or Personal Access Token (Server/Data Center)
JIRA_API_VERSION	–	3 for Cloud (default), 2 for Server/Data Center
JIRA_VERIFY_SSL	–	true/false (default: true)
MAX_TOKEN_CALL	–	Token limit per tool response (default: 20000)
MCP_TRANSPORT	–	stdio (default) or http
MCP_HTTP_PORT	–	HTTP server port (default: 3002)
MCP_HTTP_HOST	–	HTTP server host (default: localhost)

* JIRA_EMAIL is required for Jira Cloud. Leave empty for Jira Server / Data Center (use PAT only).

Available Tools

Tool	Description
jira_health_check	Test connection, verify account info and server version
search_issues	Search issues using JQL — find incidents, open vulnerabilities, remediation tasks
get_issue	Get full details of a single issue including comments and history
create_issue	Create a new issue (incident, task, bug, etc.)
update_issue	Update summary, description, priority, or labels
add_comment	Add a comment to record investigation findings
list_transitions	List available status transitions for an issue
transition_issue	Move an issue to a new status (e.g. In Progress, Resolved, Closed)
list_projects	List all accessible Jira projects with keys and types

Example Queries

• "Search for all open critical security incidents in the SEC project"
• "Create a Jira ticket for the suspicious login activity from 192.168.1.100"
• "Get the full details of ticket SEC-1234 including all comments"
• "Move SEC-1234 to Resolved and add a closing comment with my findings"
• "List all Jira projects I have access to"

Debugging

Use the MCP Inspector to test and debug:

npm run inspector

Server logs are written to stderr so they do not interfere with the MCP JSON-RPC stream on stdout.

Troubleshooting

Symptom	Likely cause
401 Unauthorized	Invalid JIRA_TOKEN or wrong JIRA_EMAIL
403 Forbidden	Insufficient permissions on the project
404 Not Found	Issue key or project does not exist
ECONNREFUSED	Wrong JIRA_HOST or Jira server not reachable
SSL errors	Set JIRA_VERIFY_SSL=false for self-signed certs (Server/DC only)
Token limit exceeded	Reduce max_results or set break_token_rule: true

Development

git clone https://github.com/TocharianOU/jira-mcp.git
cd jira-mcp
npm install --ignore-scripts
npm run build
cp .env.example .env   # fill in your credentials
npm start

Release

See RELEASE.md for the full release process.

License

Apache 2.0 — Copyright © 2024 TocharianOU Contributors