mattjegan/swarmia-mcp

A Model Context Protocol (MCP) server that provides access to Swarmia's Export API. This server allows you to fetch various metrics and reports from Swarmia including pull request metrics, DORA metrics, investment balance reports, software capitalization reports, and effort reporting.
Features
This MCP server provides access to the following Swarmia Export API endpoints:
- **Pull Request Metrics** - Cycle time, review rate, merge time, PRs in progress, etc.
- **DORA Metrics** - Deployment frequency, change lead time, change failure rate, mean time to recovery
- **Investment Balance** - Monthly FTE data and investment category breakdowns
- **Software Capitalization Report** - Employee contributions to capitalizable work
- **Software Capitalization Employees** - FTE effort breakdown by month for each employee
- **Effort Reporting** - Authors and their FTE for each issue in a given month
Prerequisites
- Python 3.8 or higher
- A Swarmia account with API access
- A Swarmia API token (obtain from Settings/API tokens in your Swarmia dashboard)
Integration with MCP Clients
To use this MCP server with your favourite MCP client (E.g. Claude, Cursor etc.):
1. **Ensure depedancies are installed**
2. **Add the following to your MCP configuration**
3. **Restart your client application**
4. **Ask for some metrics**
Example queries:
- "Analyze our team's pull request cycle time trends"
- "Get the software capitalization report for Q1 2024"
- "Show me effort reporting for last month"
Installation for Development
1. Clone or download this repository
2. Install the required dependencies and setup the project:
3. Set up your Swarmia API token as an environment variable:
Quick Setup
For a complete setup including dependency installation and environment checks:
Usage
Running the MCP Server
To run the server:
Or directly:
The server will start and listen for MCP client connections via stdio.
Available Tools
The server provides the following tools:
1. get_pull_request_metrics
Get pull request metrics for the organization.
**Parameters:**
- timeframe (optional): Predefined timeframe (last_7_days, last_14_days, last_30_days, etc.)
- start_date (optional): Start date in YYYY-MM-DD format (alternative to timeframe)
- end_date (optional): End date in YYYY-MM-DD format (alternative to timeframe)
- timezone (optional): Timezone for data aggregation (default: UTC)
**Returns:** CSV data with columns including Start Date, End Date, Team, Cycle Time, Review Rate, Time to first review, PRs merged/week, Merge Time, PRs in progress, Contributors.
2. get_dora_metrics
Get DORA metrics for the organization.
**Parameters:**
- timeframe (optional): Predefined timeframe
- start_date (optional): Start date in YYYY-MM-DD format
- end_date (optional): End date in YYYY-MM-DD format
- timezone (optional): Timezone for data aggregation
- app (optional): Deployment application name(s), comma-separated
- environment (optional): Deployment environment(s), comma-separated
**Returns:** CSV data with DORA metrics including Deployment Frequency, Change Lead Time, Average Time to Deploy, Change Failure Rate, Mean Time to Recovery, Deployment Count.
3. get_investment_balance
Get investment balance statistics using the Effort model.
**Parameters:**
- start_date (required): First day of the month in YYYY-MM-DD format
- end_date (required): Last day of the month in YYYY-MM-DD format
- timezone (optional): Timezone for data aggregation