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

Shared optional parameters

All time-series endpoints accept:

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

DORA-specific parameters

FTE-specific parameters

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