JIRA MCP Server

A production-grade Model Context Protocol (MCP) server that exposes JIRA sprint data as MCP Tools and Prompts.

Ships with rich in-memory mock data (30 issues, 8 assignees) and a pluggable JiraClient abstraction that makes connecting to a real Atlassian JIRA instance a drop-in upgrade.

---

Features

Category	Detail
Transport	SSE (HTTP) — compatible with Cursor, Claude.ai Web, and any SSE-capable MCP client
Tools	get_active_sprint_issues, get_issue_details
Prompts	format_sprint_progress, format_issue_details
Data layer	Abstract JiraClient — swap mock ↔ real API via env var
Models	Pydantic v2 with full type safety

---

Project Structure

jira-mcp-server/
├── main.py                         # Entry point (SSE server)
├── pyproject.toml
└── src/
    ├── data/
    │   ├── models.py               # Pydantic v2 models (JiraIssue, Assignee, SprintMeta)
    │   └── mock_issues.py          # 30 mock issues + SPRINT_META
    ├── jira/
    │   ├── __init__.py             # get_jira_client() factory
    │   ├── base.py                 # Abstract JiraClient (ABC)
    │   ├── mock_client.py          # MockJiraClient — in-memory fixture data
    │   └── api_client.py           # ApiJiraClient — real JIRA REST stub
    ├── server/
    │   ├── app.py                  # FastMCP instance + client initialisation
    │   └── tools.py                # @mcp.tool registrations
    └── prompts/
        ├── sprint_progress.py      # @mcp.prompt: format_sprint_progress
        └── issue_details.py        # @mcp.prompt: format_issue_details

---

Quick Start

Prerequisites

• Python 3.12+
• uv (recommended) or pip

Install dependencies

uv sync

Run the server

# Using the installed script:
uv run jira-mcp-server

# Or directly:
uv run python main.py

The SSE server starts at http://localhost:8000/sse by default.

Override host/port via environment variables:

MCP_HOST=127.0.0.1 MCP_PORT=9000 uv run jira-mcp-server

---

MCP Client Configuration

Cursor

Add to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "jira": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "url": "http://localhost:8000/sse"
    }
  }
}

---

Tools

get_active_sprint_issues

Returns all issues in the active sprint for the provided Scrum board name as a JSON array.

{ "scrum_board_name": "Platform Engineering Scrum Board" }

get_issue_details

Returns the full details of a single issue.

{ "issue_id": "PROJ-1" }

Raises an error if the issue key does not exist.

---

Prompts

format_sprint_progress

Generates a comprehensive scrum master report in Markdown:

• Sprint Overview table (totals, velocity, completion %)
• Blockers section (table + impact analysis per blocker)
• Risk Analysis (Critical + High items not Done)
• Resource Utilisation table (per-assignee: issues, SP, completion %)
• Bandwidth Analysis (overloaded / under-utilised members + rebalancing suggestions)
• Key Insights (patterns, anomalies)
• Recommended Next Steps (prioritised action list)

{
  "sprint_data_json": "{\"sprint_meta\":{...},\"issues\":[...]}"
}

sprint_data_json should be the JSON payload returned by tools (metadata + issues), or an issues-only JSON array.

format_issue_details

Renders a single issue as a structured Markdown document with:

• Header (ID + Summary + Type + Status + Priority)
• Metadata table (all fields)
• Description section
• Acceptance Criteria checklist (auto-checked if status = Done)
• Labels

{
  "issue_json": "{\"id\":\"PROJ-5\",...}"
}

issue_json should be the JSON object returned by get_issue_details.

---

Connecting to Real JIRA

The JiraClient abstraction makes this a configuration-only change:

1. Set the following environment variables:

   JIRA_BASE_URL=https://your-org.atlassian.net
   JIRA_EMAIL=service-account@your-org.com
   JIRA_API_TOKEN=your-atlassian-api-token
   JIRA_BOARD_ID=3
   JIRA_PROJECT_KEY=PROJ
   

2. Fill in the TODO sections in src/jira/api_client.py:

   • Uncomment the httpx import and install httpx (uv add httpx)
   • Implement get_sprint_issues, get_issue, and get_sprint_meta using the JIRA Agile REST API v1 and REST API v3 endpoints documented inline

3. Restart the server — the factory auto-selects ApiJiraClient when JIRA_API_TOKEN is present.

No changes to tools, prompts, or server code are required.

---

Development

Inspect with MCP Inspector

uv run mcp dev main.py

Opens the interactive MCP Inspector in your browser with all tools and prompts available for testing.

Static analysis

uv run mypy src/ main.py
uv run ruff check src/ main.py