jira-mcp

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