# mattjegan/swarmia-mcp [Health: Active]

**Category:** 📊 Monitoring  
**Repository:** https://github.com/mattjegan/swarmia-mcp  
**GitHub Stars:** 8  
**Views:** 4  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mattjegan-swarmia-mcp

## Description
Read-only MCP server to help gather metrics from Swarmia for quick reporting.

## Tools
Capabilities this server exposes over MCP:

- **timeframe**
- **last_7_days**
- **last_14_days**
- **last_30_days**
- **start_date**
- **end_date**
- **timezone**
- **app**
- **environment**
- **year**
- **month**
- **custom_field**
- **group_by**
- **highestLevelIssue**
- **lowestLevelIssue**
- **customField**

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "swarmia-mcp": {
    "command": "npx",
    "args": ["-y","mattjegan-swarmia-mcp"],
    "env": {
      "SWARMIA_API_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `SWARMIA_API_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mattjegan/swarmia-mcp MCP server does

The mattjegan/swarmia-mcp MCP server connects MCP clients to the Swarmia Export API. It is intended for read-only retrieval of engineering and delivery data rather than updating Swarmia records. Results are returned as CSV data, making them suitable for analysis or reporting workflows handled by an MCP client.

The available reporting areas are:

- Pull request performance, including cycle time, review rate, merge time, work in progress, and contributors.
- DORA metrics, including deployment frequency, change lead time, change failure rate, recovery time, and deployment counts.
- Investment balance data with investment categories, FTE months, percentages, and activity counts.
- Software capitalization reports covering employee contributions and developer months.
- Monthly employee capitalization effort.
- Effort reporting by author and issue, with optional custom fields and grouping.

## How it works

The server runs as a local MCP process and communicates with the client over standard input and output. It sends authenticated requests to Swarmia's Export API at `https://app.swarmia.com/api/v0`. Authentication uses a Swarmia API token passed by the server as a query parameter on requests.

The mattjegan/swarmia-mcp MCP server supports predefined periods such as the last 7, 14, 30, 60, 90, 180, or 365 days. Pull request and DORA requests can instead use explicit start and end dates. Timezone values use tz database identifiers, with UTC as the default. DORA queries can filter by deployment application and environment.

## Setup and configuration

The project requires Python 3.8 or later, a Swarmia account with API access, and a Swarmia API token created in the Swarmia dashboard under Settings/API tokens. Install the project dependencies with `make install`; `make setup` provides the documented combined setup and environment-check path.

Set the required environment variable before starting the process:

```bash
export SWARMIA_API_TOKEN="your_api_token_here"
```

MCP client configuration points to the Python interpreter in the project's virtual environment and the `swarmia_mcp_server.py` file. The README gives examples for clients including Claude and Cursor. The server can also be started with `make run` or directly with `python3 swarmia_mcp_server.py`.

## Tools and capabilities

The six documented tools are `get_pull_request_metrics`, `get_dora_metrics`, `get_investment_balance`, `get_software_capitalization_report`, `get_software_capitalization_employees`, and `get_effort_reporting`.

The first two accept timeframes or date ranges and a timezone. Investment and capitalization reports require month-boundary dates. The employee report requires a year. Effort reporting requires the first day of a month and can include a Jira custom field, grouping rows by the highest-level issue, lowest-level issue, or custom field.

## Limitations and notes

The mattjegan/swarmia-mcp MCP server requires valid Swarmia API access and permissions for the requested data. Invalid or expired tokens can produce authentication errors, while insufficient permissions can produce authorization errors. Network failures, invalid parameters, and API rate limits are also handled as error conditions. The supplied material does not document a hosted endpoint, package distribution, or license.

_Full upstream README: https://allmcps.com/mcp/mattjegan-swarmia-mcp/readme_