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 |