mcp-swarmia

A local Model Context Protocol (MCP) server that exposes the Swarmia Export API as tools for AI assistants such as Claude.

Once connected, Claude (or any MCP-compatible client) can query your engineering metrics—pull request cycle times, DORA metrics, investment balance, CapEx reports, and FTE effort—in natural language without you having to write a single API call.

---

Requirements

• Python 3.11+
• A Swarmia account with an API token (Settings → API tokens)
• mcp Python package (only external dependency)

---

Installation

# 1. Clone or copy this directory
cd mcp-swarmia

# 2. Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

---

Configuration

Export your Swarmia API token as an environment variable:

export SWARMIA_API_TOKEN="your-token-here"

Alternatively, add it to a .env file and source it, or configure it in your MCP client settings (see below).

---

Running the server

python server.py

The server communicates over stdio (standard input/output), which is the transport expected by Claude Desktop and most other MCP clients. You do not need to expose any network ports.

---

Connecting to Claude Desktop

Add the following block to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "swarmia": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-swarmia/server.py"],
      "env": {
        "SWARMIA_API_TOKEN": "your-token-here"
      }
    }
  }
}

Replace the paths and token with your actual values, then restart Claude Desktop.

---

Available tools

Tool	Description	Required params
get_pull_requests	Team-level PR metrics (cycle time, review time, size, …)	—
get_dora_metrics	Organisation DORA metrics (deployment frequency, lead time, CFR, MTTR)	—
get_investment_balance	Monthly FTE investment balance by category	startDate, endDate
get_capex	Software capitalisation report	startDate, endDate
get_capex_employees	Per-employee CapEx breakdown	year
get_fte	Monthly engineering effort (FTE) by author	month

Shared optional parameters

All time-series endpoints accept:

Parameter	Description	Example
timeframe	Preset window	last_30_days
startDate	Custom start (YYYY-MM-DD)	2024-01-01
endDate	Custom end (YYYY-MM-DD)	2024-03-31
timezone	tz database identifier	America/New_York

timeframe and startDate/endDate are mutually exclusive. Defaults to last_7_days when neither is provided.

DORA-specific parameters

Parameter	Description
app	Filter by deployment application name
environment	Filter by deployment environment

FTE-specific parameters

Parameter	Description	Values
groupBy	How to group effort	highestLevelIssue (default), lowestLevelIssue, customField
customField	Jira field ID	Required when groupBy=customField

---

Response format

All tools return CSV text with a header row and comma delimiters, exactly as returned by the Swarmia API. No summary aggregations are added.

---

Example prompts

After connecting the server to Claude, try:

• "Show me our DORA metrics for the last 30 days."
• "What does our pull request cycle time look like for Q1 2024?"
• "Fetch the investment balance for January 2024."
• "Get the CapEx report for 2024."
• "Show FTE effort for March 2024, grouped by highest-level issue."

---

Security note

Swarmia recommends passing tokens via the Authorization header rather than query parameters, as some proxies log query strings. This server always uses the header approach.

---

Troubleshooting

Problem	Solution
SWARMIA_API_TOKEN is not set	Export the env var or add it to your MCP client config
HTTP 401	Token is invalid or expired — regenerate it in Swarmia
HTTP 400	Check that required parameters (e.g. startDate/endDate) are provided and in the correct format
Server not appearing in Claude	Verify the absolute paths in claude_desktop_config.json and restart Claude Desktop