Jira / Confluence Team Lead MCP

An MCP server that answers three questions for a team lead, and can publish the answer to Confluence:

1. What's in this sprint, and what still needs refinement?

2. How did each developer do over the last few sprints? (real changelog-derived cycle/lead time, not a guess from current status)

3. What's not ready for the next refinement session, and who should be in the room?

Built and tested against a personal Atlassian Cloud site first; the target corporate instance is a .env change, not a code change.

Setup

python -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[dev]"

Copy .env.example to .env and fill in the base URL, your Atlassian email, and an API token from https://id.atlassian.com/manage-profile/security/api-tokens.

Then register the server (.mcp.json in this repo already does it for Claude Code — adjust the absolute paths if you move the project):

claude mcp add jira-confluence -- "C:\DEV\Jira Confluence MCP\.venv\Scripts\python.exe" -m jira_confluence_mcp.server

First call should always be check_connection — it verifies both products, prints the resolved defaults, and tells you which custom field it picked for story points.

Related MCP server: MCP Jira DevFlow

Tools

Every report tool returns rows (structured), markdown (for reading), and — with include_confluence_storage=true — confluence (storage format). Pass publish=true to write it straight to a page; re-running overwrites the same page by title.

Metric definitions

These are the decisions baked into metrics.py. Worth agreeing with the team before the numbers get used in a retro.

• Completed — the issue was in a Done-category status at sprint close (completeDate, else endDate, else now for an active sprint). Judged at sprint close, so an issue finished the week after the sprint ended counts as carried over for that sprint.

• Carried over — everything in the sprint that was not completed.

• Re-opened work — an issue that was Done and moved back out is not completed. Closed → re-opened → closed again reports the final close.

• Time in progress — calendar hours in In Progress-category statuses, summed across visits, capped at completion or sprint close.

• Cycle time — first entry into an In Progress-category status → completion.

• Lead time — issue created → completion.

• Grouping — by the issue's current assignee. Reassigned work is credited to whoever holds it now; the changelog has the data to split it by holder if that turns out to matter.

Status categories (new / indeterminate / done) are read from the instance rather than hard-coded status names, so a workflow that calls it "Development" instead of "In Progress" still works. Any status the instance does not report is surfaced in the report's warnings.

Confluence tables

Storage-format tables are static — not sortable or filterable. Options, in the order worth trying on a target instance:

1. table_style="table-filter" — wraps the table in the Table Filter, Charts & Spreadsheet macro. Run check_confluence_capabilities first; reading the app inventory needs admin rights, so a null result means "ask an admin", not "not installed".

2. Confluence Cloud's database content type — behaves like an embedded spreadsheet, but cannot be created through the REST content API this server uses. Manual setup only for now.

3. table_style="plain" (default) — static table. Re-run the report grouped or sorted differently when another view is needed. Good enough for MVP.

Switching to another instance

Only .env changes:

• JIRA_BASE_URL / CONFLUENCE_BASE_URL — set both explicitly if Jira and Confluence are on different hosts (usual for Data Center).

• ATLASSIAN_DEPLOYMENT — leave auto unless the URL doesn't give it away. Data Center means /rest/api/2 and offset-paged search; the client handles the switch, including falling back from the Cloud-only /search/jql.

• JIRA_STORY_POINTS_FIELD — auto-discovery looks for "Story Points" / "Story point estimate"; pin the custom field id if the instance renamed it.

• REFINEMENT_DOR_LABELS / REFINEMENT_DOD_LABELS — the team's actual labels.

• ATLASSIAN_CA_BUNDLE — corporate root CA, for an internal TLS chain. Prefer this over turning ATLASSIAN_VERIFY_SSL off.

Tests

.venv\Scripts\python.exe -m pytest -q

52 tests, no instance required — HTTP is mocked with respx, and the metric logic is tested as pure functions over changelog fixtures.

Not built yet

• get_story_comment_summary — per-developer comment timeline within a story. Deliberately deferred; decide whether it merges into the developer history or stays standalone once the first three tools have been used for a few sprints.

• Alerting on stories with no comment for >1 day.

• Postgres sync + front end. The rows payloads are already shaped for a table-per-report load, so that phase doesn't need the reports rewritten.