jira-mcp

MCP server for Jira Cloud — tailored for ALM projects with Zephyr Scale integration.

Built on the Model Context Protocol SDK (TypeScript). Runs as a local stdio process used by Claude Code.

---

Setup

cp .env.dist .env
# Fill in your values in .env
npm install
npm run build

Then register in your Claude config (~/.claude/claude_desktop_config.json or equivalent):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp/build/index.js"]
    }
  }
}

---

Configuration

See .env.dist for all available variables.

Variable	Required	Description
JIRA_HOST	✅	e.g. your-company.atlassian.net
JIRA_USERNAME	✅	Your Atlassian email
JIRA_API_TOKEN	✅	API token from id.atlassian.com
JIRA_PROJECT_KEY	✅	e.g. ALM
ZEPHYR_API_TOKEN	—	Required for test step tools
AUTO_CREATE_TEST_TICKETS	—	Auto-create Test ticket when a Story has points (default: true)

Custom field IDs (story points, acceptance criteria, epic link, etc.) are configurable via env — see .env.dist.

---

Tools

Issues

Tool	Description
create-ticket	Create a ticket (Bug, Story, Task, Test) with full field support
get-ticket	Get ticket details
update-ticket	Update any field: summary, description, labels, priority, assignee, sprint…
search-tickets	Search by issue type with optional JQL criteria
search-tickets-jql	Free JQL search
transition-ticket	Move a ticket through its workflow (with optional comment)
assign-ticket	Assign or unassign a ticket
get-issue-history	Full changelog of a ticket
get-related-issues	Linked issues (blocks, is blocked by, relates to…)
get-dev-info	PRs, branches and commits linked via GitHub integration

Comments & Time

Tool	Description
add-comment	Add a comment (Markdown → ADF)
list-comments	List comments on a ticket
add-worklog	Log time spent (2h 30m, 1d…) with optional comment

Watchers

Tool	Description
add-watcher	Add a watcher by account ID
remove-watcher	Remove a watcher by account ID

Links

Tool	Description
link-tickets	Create a link between two tickets

Sprints

Tool	Description
get-sprints	List sprints for a board (active / future / closed)

Zephyr Scale (test steps)

Tool	Description
get-test-steps	Get test steps from a Test ticket
add-test-steps	Add test steps to a Test ticket

---

Markdown support

Descriptions and comments accept Markdown — converted to Atlassian Document Format (ADF) automatically:

• ## Heading / ### Sub-heading
• - bullet list
• `inline code`
• **bold**

---

Development

npm run build      # Compile TypeScript → build/

Restart Claude (or /mcp) to pick up a new build.