mcp-server-jira

An MCP (Model Context Protocol) server that lets an AI agent manage Jira Stories in a self-hosted Jira instance via the Jira REST API v2. Built for a PRD automation workflow.

Setup

npm install
cp .env.example .env   # then fill in your values
npm run build

Related MCP server: Jira MCP Integration

Configuration

All config comes from environment variables (loaded from .env):

Authentication uses HTTP Basic Auth: base64(JIRA_USER_EMAIL:JIRA_API_TOKEN). All API calls target ${JIRA_BASE_URL}/rest/api/2.

Running

The server speaks MCP over stdio.

npm start          # runs dist/index.js
npm run dev        # ts-node src/index.ts

Example MCP client config

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server-jira/dist/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://jira.yourcompany.com",
        "JIRA_USER_EMAIL": "bot@yourcompany.com",
        "JIRA_API_TOKEN": "...",
        "JIRA_PROJECT_KEY": "PRD"
      }
    }
  }
}

Tools

Story CRUD

Workflow & guarded actions

Agile / burndown (requires Jira Software)

Safety: human approval for risky actions

Two complementary mechanisms protect destructive operations:

1. MCP annotations — every tool declares readOnlyHint / destructiveHint / idempotentHint / openWorldHint. The host (e.g. Claude) uses these to decide when to prompt the human before running a tool. Read-only tools (get_*, search_*, list_*) are flagged as such; update_story, delete_story are flagged destructive.

2. Server-enforced confirmation — delete_story and terminal transition_story calls require an explicit confirm: true. Without it the tool performs no API call and instead returns a requires_confirmation warning describing the impact, so the agent (and human) must opt in deliberately.

Burndown charts

An MCP server can't return a rendered chart image, but get_sprint_burndown returns the underlying data: a reliable computed summary (committed/completed/ remaining story points and issue counts by status, derived from the sprint's issues) plus a best-effort raw GreenHopper burndown time-series (burndown_chart_raw) when that internal endpoint is available. The AI can summarize progress, flag scope changes, and describe the burndown from this data. Story points are read from JIRA_STORY_POINTS_FIELD.

All tools return structured JSON. Errors are returned as structured objects ({ error: true, message, ... }) — the server never throws unhandled exceptions out of a tool. Logs are written to stderr only; stdout is reserved for the MCP protocol.