Swarmia MCP Server

1# Swarmia MCP Server
2 
3A 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.
4 
5## Features
6 
7This MCP server provides access to the following Swarmia Export API endpoints:
8 
9- **Pull Request Metrics** - Cycle time, review rate, merge time, PRs in progress, etc.
10- **DORA Metrics** - Deployment frequency, change lead time, change failure rate, mean time to recovery
11- **Investment Balance** - Monthly FTE data and investment category breakdowns
12- **Software Capitalization Report** - Employee contributions to capitalizable work
13- **Software Capitalization Employees** - FTE effort breakdown by month for each employee
14- **Effort Reporting** - Authors and their FTE for each issue in a given month
15 
16## Prerequisites
17 
18- Python 3.8 or higher
19- A Swarmia account with API access
20- A Swarmia API token (obtain from Settings/API tokens in your Swarmia dashboard)
21 
22## Integration with MCP Clients
23 
24To use this MCP server with your favourite MCP client (E.g. Claude, Cursor etc.):
25 
261. **Ensure depedancies are installed**
27```bash
28make install
29```
30 
312. **Add the following to your MCP configuration**
32```json
33   {
34     "mcpServers": {
35       "swarmia": {
36         "command": "/path/to/swarmia-mcp/venv/bin/python3",
37         "args": ["/path/to/swarmia-mcp/swarmia_mcp_server.py"],
38         "env": {
39           "SWARMIA_API_TOKEN": "your_api_token_here"
40         }
41       }
42     }
43   }
44```
45 
463. **Restart your client application**
47 
484. **Ask for some metrics**
49   Example queries:
50     - "Analyze our team's pull request cycle time trends"
51     - "Get the software capitalization report for Q1 2024"
52     - "Show me effort reporting for last month"
53 
54## Installation for Development
55 
561. Clone or download this repository
572. Install the required dependencies and setup the project:
58 
59```bash
60make install
61```
62 
633. Set up your Swarmia API token as an environment variable:
64 
65```bash
66export SWARMIA_API_TOKEN="your_api_token_here"
67```
68 
69### Quick Setup
70 
71For a complete setup including dependency installation and environment checks:
72 
73```bash
74make setup
75```
76 
77## Usage
78 
79### Running the MCP Server
80 
81To run the server:
82 
83```bash
84make run
85```
86 
87Or directly:
88 
89```bash
90python3 swarmia_mcp_server.py
91```
92 
93The server will start and listen for MCP client connections via stdio.
94 
95### Available Tools
96 
97The server provides the following tools:
98 
99#### 1. `get_pull_request_metrics`
100Get pull request metrics for the organization.
101 
102**Parameters:**
103- `timeframe` (optional): Predefined timeframe (`last_7_days`, `last_14_days`, `last_30_days`, etc.)
104- `start_date` (optional): Start date in YYYY-MM-DD format (alternative to timeframe)
105- `end_date` (optional): End date in YYYY-MM-DD format (alternative to timeframe)
106- `timezone` (optional): Timezone for data aggregation (default: UTC)
107 
108**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.
109 
110#### 2. `get_dora_metrics`
111Get DORA metrics for the organization.
112 
113**Parameters:**
114- `timeframe` (optional): Predefined timeframe
115- `start_date` (optional): Start date in YYYY-MM-DD format
116- `end_date` (optional): End date in YYYY-MM-DD format
117- `timezone` (optional): Timezone for data aggregation
118- `app` (optional): Deployment application name(s), comma-separated
119- `environment` (optional): Deployment environment(s), comma-separated
120 
121**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.
122 
123#### 3. `get_investment_balance`
124Get investment balance statistics using the Effort model.
125 
126**Parameters:**
127- `start_date` (required): First day of the month in YYYY-MM-DD format
128- `end_date` (required): Last day of the month in YYYY-MM-DD format
129- `timezone` (optional): Timezone for data aggregation
130 
131**Returns:** CSV data with investment categories, FTE months, relative percentages, and activity counts.
132 
133#### 4. `get_software_capitalization_report`
134Get software capitalization report with employee contributions.
135 
136**Parameters:**
137- `start_date` (required): First day of the start month in YYYY-MM-DD format
138- `end_date` (required): Last day of the end month in YYYY-MM-DD format
139- `timezone` (optional): Timezone for data aggregation
140 
141**Returns:** CSV data with employee details, capitalizable work, developer months, and additional context.
142 
143#### 5. `get_software_capitalization_employees`
144Get list of employees with FTE effort breakdown by month.
145 
146**Parameters:**
147- `year` (required): Year for the report (e.g., 2024)
148- `timezone` (optional): Timezone for data aggregation
149 
150**Returns:** CSV data with employee details and monthly FTE breakdowns.
151 
152#### 6. `get_effort_reporting`
153Get effort reporting for authors and their FTE for each issue.
154 
155**Parameters:**
156- `month` (required): Month in YYYY-MM-DD format (first day of the month)
157- `timezone` (optional): Timezone for data aggregation
158- `custom_field` (optional): Jira field ID to include as Custom field column
159- `group_by` (optional): How FTE rows should be grouped (`highestLevelIssue`, `lowestLevelIssue`, `customField`)
160 
161**Returns:** CSV data with author details, FTE contributions, and issue information.
162 
163## Configuration
164 
165### Environment Variables
166 
167- `SWARMIA_API_TOKEN`: Your Swarmia API token (required)
168 
169### Timeframes
170 
171The following predefined timeframes are available:
172- `last_7_days`
173- `last_14_days`
174- `last_30_days`
175- `last_60_days`
176- `last_90_days`
177- `last_180_days`
178- `last_365_days`
179 
180### Timezones
181 
182You can specify any timezone using tz database identifiers (e.g., `America/New_York`, `Europe/London`, `Asia/Tokyo`). The default is UTC.
183 
184## API Reference
185 
186This MCP server is based on the [Swarmia Export API documentation](https://help.swarmia.com/getting-started/integrations/data-export/export-api).
187 
188### Base URL
189```
190https://app.swarmia.com/api/v0
191```
192 
193### Authentication
194The server uses token-based authentication. Your API token is passed as a query parameter to all requests.
195 
196## Error Handling
197 
198The server includes comprehensive error handling for:
199- Missing or invalid API tokens
200- HTTP request failures
201- Invalid parameters
202- API rate limiting
203- Network connectivity issues
204 
205## Logging
206 
207The server logs all activities at the INFO level. You can adjust the logging level by modifying the `logging.basicConfig()` call in the server code.
208 
209## Development
210 
211### Available Make Targets
212 
213The project includes a comprehensive Makefile with the following targets:
214 
215- `make help` - Show available targets and help information
216- `make install` - Install dependencies and setup the project
217- `make setup` - Complete setup (install + environment checks)
218- `make test` - Test the API connection and server functionality
219- `make run` - Run the MCP server
220- `make check-env` - Check if required environment variables are set
221- `make clean` - Clean up temporary files
222- `make format` - Format code with black (if available)
223- `make lint` - Lint code with flake8 (if available)
224- `make type-check` - Type check with mypy (if available)
225- `make quality` - Run all quality checks
226- `make info` - Show project information
227 
228### Testing
229 
230To test the server:
231 
232```bash
233make test
234```
235 
236## Example Usage
237 
238Here's an example of how you might use this server with an MCP client:
239 
240```python
241# Example: Get pull request metrics for the last 30 days
242result = await client.call_tool(
243    "get_pull_request_metrics",
244    {
245        "timeframe": "last_30_days",
246        "timezone": "America/New_York"
247    }
248)
249 
250# Example: Get DORA metrics for a specific date range
251result = await client.call_tool(
252    "get_dora_metrics",
253    {
254        "start_date": "2024-01-01",
255        "end_date": "2024-01-31",
256        "app": "my-app",
257        "environment": "production"
258    }
259)
260 
261# Example: Get investment balance for January 2024
262result = await client.call_tool(
263    "get_investment_balance",
264    {
265        "start_date": "2024-01-01",
266        "end_date": "2024-01-31"
267    }
268)
269```
270 
271## Troubleshooting
272 
273### Common Issues
274 
2751. **"SWARMIA_API_TOKEN environment variable is required"**
276   - Make sure you've set the `SWARMIA_API_TOKEN` environment variable
277   - Verify your token is valid and has the necessary permissions
278 
2792. **"API request failed with status 401"**
280   - Your API token may be invalid or expired
281   - Check your token in the Swarmia dashboard
282 
2833. **"API request failed with status 403"**
284   - Your token may not have permission to access the requested data
285   - Contact your Swarmia administrator
286 
2874. **"Request failed: Connection timeout"**
288   - Check your internet connection
289   - Verify that `app.swarmia.com` is accessible from your network
290 
291### Getting Help
292 
293- Check the [Swarmia Export API documentation](https://help.swarmia.com/getting-started/integrations/data-export/export-api)
294- Review the Swarmia API token settings in your dashboard
295- Contact Swarmia support for API-related issues
296