jira-worktrack-mcp

A zero-dependency MCP server that answers the questions people actually ask about work in Jira — what is on my plate, what did I do yesterday, where is the sprint bleeding, which tickets are not ready for development, what has been waiting too long — instead of returning raw issue JSON to sort through.

Jira is the single source of truth; nothing is stored locally except downloaded attachments. Everything is read-only apart from upload_attachments, which is the single tool that changes anything — guard it with a permission rule:

{ "permissions": { "ask": ["mcp__jira-worktrack__upload_attachments"] } }

Replace YOUR-ORG below with the account or organisation you host this repo under.

Install

/plugin marketplace add YOUR-ORG/jira-worktrack-mcp
/plugin install jira-worktrack@jira-tools

Or as a standalone MCP server:

curl -fsSL https://raw.githubusercontent.com/YOUR-ORG/jira-worktrack-mcp/main/bootstrap.sh | bash

The installer asks for your Jira site, your Atlassian e-mail and an API token (create one at https://id.atlassian.com/manage-profile/security/api-tokens). For the site you can type just the name — acme becomes https://acme.atlassian.net.

Tools

For developers

Tool	Answers
my_work	What is assigned to me, grouped by status, with anything untouched for days flagged.
standup	What I moved or closed since yesterday, what I am on now, what I am waiting for — read from the change history, not from memory.
next_up	What to pick up next, ranked by started/priority/sprint/age, with the reasoning shown.

For scrum masters

Tool	Answers
sprint_health	Status split, work in progress per person, unassigned items, items stuck too long, share of the sprint actually done.
flow_metrics	Cycle time and lead time (median and p90), where the time goes per status, and the slowest tickets.
stale_issues	Two kinds of silence: nobody updated it, and it never left this status.
workload	Open issues per person, split by in progress and waiting, with story points when the project uses them.

For BAs

Tool	Answers
intake_check	Which tickets lack a description, acceptance criteria, an attachment, a customer or an estimate.
waiting_on_customer	What is parked outside the team, how long, and who spoke last.
duplicate_scan	Tickets whose summaries overlap — the same request arriving twice.

Attachments

Tool	Answers
list_attachments	What is attached, and which comment each file was posted with.
download_attachments	Fetches them; inline: true shows the images straight in the reply.
render_pdf	Renders PDF pages to images, plus any annotation text — no poppler needed on macOS.
extract_attachment_text	Text out of .xlsx/.docx/.pptx, text files and text-bearing PDFs.
download_attachments_by_jql	Every attachment across the issues a query matches.
upload_attachments	Attaches local files. The only tool that writes to Jira.

For everyone

Tool	Answers
issue_timeline	One ticket's life: every status change, how long it stayed, who moved it.
team_report	Created versus resolved over a period, throughput per person, breakdown by type.
whoami	Verifies the credentials.

How the numbers are worked out

• Status categories over status names. Workflows differ per project — this site alone has in progress, Code_Review, ready_for_test and Ready To Release. Anything structural keys off Jira's statusCategory (new / indeterminate / done); the name is only used for display and for spotting "waiting" states.
• Time in status is rebuilt from each issue's changelog, requested with expand: changelog on the search itself — one call for a hundred issues rather than a hundred calls.
• Cycle time starts at the first move into a status that is neither backlog nor done. A ticket taken straight from the backlog to closed never started, so it has no cycle time and is reported separately instead of being counted as zero.
• Duplicate scan compares normalised summary words (Jaccard). Pairs that share a parent, and story/test pairs, are skipped — those repeat a summary on purpose.
• Caps are reported, never silent: when a tool stops at its issue limit it says so.

Configuration

Env var	Default	Meaning
JIRA_BASE_URL	—	e.g. https://your-site.atlassian.net
JIRA_EMAIL	—	Atlassian account e-mail
JIRA_API_TOKEN	—	Atlassian API token
JIRA_TIMEOUT_MS	30000	Request timeout
JIRA_MAX_RETRIES	3	Retries on timeout, 429 and 5xx (honouring Retry-After)

Custom field ids differ per site, so Story Points, Sprint and the customer field are looked up by name once per session and cached.

Notes

• The API token is stored in ~/.claude.json in plain text, like every other MCP env var.
• Everything is scoped to what your own Jira account can see.
• The attachment half is shared verbatim with jira-attachments-mcp, which packages it on its own. Run one or the other, not both — otherwise the same tool names appear twice. A fix in lib/pdf.mjs, lib/extract.mjs or lib/zip.mjs needs copying across.
• Uninstall with claude mcp remove jira-worktrack --scope user.