jira-pm-mcp

An MCP server that wraps the JIRA Cloud REST API for AI-driven agile project management. Designed to be run as a daily batch by an AI agent (e.g. via OpenClaw) to monitor sprint health, sync labels, flag risks, and write audit receipts.

Requirements

• Node.js 20+

• JIRA Cloud instance

• API token with edit-issues and add-comments permissions on the target projects

Related MCP server: Jira MCP Integration

Setup

npm install
npm run build

Environment variables

Transport modes

The server supports two transport modes selected at startup.

stdio (default)

The server process is spawned and managed by the MCP client. Env vars are passed through the client config. Best for local single-user setups.

{
  "mcpServers": {
    "jira-pm": {
      "command": "node",
      "args": ["/path/to/jira-pm-mcp/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "you@company.com",
        "JIRA_API_TOKEN": "your-token"
      }
    }
  }
}

HTTP/SSE

The server runs as a persistent HTTP process. The MCP client connects to it via SSE. Best for running the server as a system service or Docker container shared across multiple clients.

Start the server:

export JIRA_BASE_URL=https://yourcompany.atlassian.net
export JIRA_EMAIL=you@company.com
export JIRA_API_TOKEN=your-token
export PORT=3000
node dist/index.js

Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "jira-pm": {
      "url": "http://localhost:3000/sse"
    }
  }
}

Endpoints:

Tools

setup_project

Configure a project for PM Agent monitoring. Must be run before any other tools. Validates connectivity and write permissions, then stores configuration as a YAML comment on the Root Epic and registers the project locally.

Returns: A checklist of validation results (root_epic, fix_versions, write_permissions, config_written) plus the config comment ID.

list_projects

List all projects registered with the PM Agent, with their configuration summary.

No parameters.

Returns: Array of projects with project_key, root_epic_key, committed_date, epic_link_field, active_statuses, and config_available.

list_fix_versions

List all fixVersions (sprints) for a project. Identifies the currently active sprint and how far through it we are.

Returns: Array of versions with name, label_equivalent (spaces replaced with hyphens), start_date, release_date, is_active, is_released, and elapsed_pct.

get_sprint_health

Read-only full sprint health snapshot. Builds the full dependency graph — stories → blocking tasks → dates and status — without making any changes to JIRA. Safe to call at any time.

Returns:

• Sprint metadata (dates, elapsed_pct, committed_date)

• Summary counts (total_stories, stories_with_no_tasks, stories_past_sprint_end, tasks_missing_dates, orphaned_tasks)

• Per-story breakdown: effective_completion_date (max end date across blocking tasks), past_sprint_end, past_committed_date, has_date_gap, and the full list of blocking tasks with their dates, assignees, and current pm-* labels

• orphaned_tasks: tasks under the root epic that don't block any story in this sprint

run_sprint_audit

Run the daily PM audit for a sprint. This is the main write tool — it applies all label and date changes to JIRA and writes an audit receipt to the Root Epic.

What it does (in order):

1. Sync sprint labels — adds the sprint label (fixVersion with spaces → hyphens) to all blocking tasks in the sprint

2. Compute task flags — evaluates each blocking task and applies pm-flag-* labels:

   • Date slip: end date past sprint boundary (pm-flag-critical-date-slip, pm-flag-warn-date-approaching)

   • Commitment risk: end date past committed_date (pm-flag-task-beyond-commitment)

   • Not started: task in Backlog/Todo at mid-sprint (pm-flag-critical-not-started, pm-flag-warn-not-started)

   • Stalled: no status change for more than stalled_threshold_days (pm-flag-warn-stalled)

3. Compute story flags — evaluates each story:

   • Stories whose effective_completion_date slips past the sprint end or committed_date (pm-flag-story-at-risk, pm-flag-story-beyond-commitment)

   • Stories with missing blocking tasks (pm-flag-missing-tasks)

   • Stories with date gaps between blocking tasks (pm-flag-date-gap)

   • Stories recommended for deferral (pm-flag-recommend-defer)

4. Update story due dates — sets each story's duedate to its effective_completion_date (max end date of blocking tasks)

5. Velocity calculation — if committed_date is set, samples up to 5 past released sprints, computes average velocity, and projects expected completion date

6. Write audit receipt — posts a YAML receipt comment to the Root Epic

Tasks with pm-acknowledged are skipped entirely (human override).

Returns: Summary of changes made, label_changes, story_date_changes, tasks_needing_dates, defer_recommendations, velocity result, and receipt_comment_id.

rollback_audit

Reverse the label and story date changes made by a previous run_sprint_audit. Reads the audit receipt from the Root Epic and applies the inverse diff. Never removes pm-acknowledged labels.

Returns: rolled_back_audit, changes_reversed, errors, and rollback_receipt_comment_id.

search_issues

Escape hatch for ad-hoc JQL queries. Returns a page of matching issues with key, summary, status, assignee, labels, fixVersions, and due date. Use the high-level tools (get_sprint_health, run_sprint_audit) for routine PM operations.

Returns: total, start_at, max_results, returned, and issues array.

pm-* label taxonomy

The agent owns the full pm-* label namespace. All managed labels are cleared and recomputed on each audit run. The one exception is pm-acknowledged — set by a human to suppress all agent flags on that issue; the agent never removes it.

Sprint labels (e.g. SIT-27-02-2026) are also applied to blocking tasks by the audit — these are derived from fixVersion names with spaces replaced by hyphens.

Authority model

Architecture

src/
  server.ts           — MCP server entry point, registers all tools
  tools/              — One file per MCP tool
  jira/               — JIRA REST API client wrappers (client, search, issues, versions, comments)
  audit/              — Core audit logic (graph, flags, velocity, receipt)
  config/             — Project config schema, JIRA-backed storage, local registry
  utils/              — Labels, dates, JQL builder

Configuration is stored as a YAML comment on the Root Epic in JIRA (prefixed with ## pm-agent-config), making it portable and version-controlled alongside the project. A local .jira-pm-registry.json maps project_key → root_epic_key to bootstrap config reads without a prior JIRA call.