Rootly MCP Server

1<!-- mcp-name: com.rootly/mcp-server -->
2# Rootly MCP Server
3 
4[![PyPI version](https://badge.fury.io/py/rootly-mcp-server.svg)](https://pypi.org/project/rootly-mcp-server/)
5[![PyPI - Downloads](https://img.shields.io/pypi/dm/rootly-mcp-server)](https://pypi.org/project/rootly-mcp-server/)
6[![Python Version](https://img.shields.io/pypi/pyversions/rootly-mcp-server.svg)](https://pypi.org/project/rootly-mcp-server/)
7[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=rootly&config=eyJ1cmwiOiJodHRwczovL21jcC5yb290bHkuY29tL3NzZSIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8WU9VUl9ST09UTFlfQVBJX1RPS0VOPiJ9fQ==)
8 
9An MCP server for the [Rootly API](https://docs.rootly.com/api-reference/overview) that integrates seamlessly with MCP-compatible editors like Cursor, Windsurf, and Claude. Resolve production incidents in under a minute without leaving your IDE.
10 
11![Demo GIF](https://raw.githubusercontent.com/Rootly-AI-Labs/Rootly-MCP-server/refs/heads/main/rootly-mcp-server-demo.gif)
12 
13## Prerequisites
14 
15- Python 3.12 or higher
16- `uv` package manager
17  ```bash
18  curl -LsSf https://astral.sh/uv/install.sh | sh
19  ```
20- [Rootly API token](https://docs.rootly.com/api-reference/overview#how-to-generate-an-api-key%3F) with appropriate permissions (see below)
21 
22### API Token Permissions
23 
24The MCP server requires a Rootly API token. Choose the appropriate token type based on your needs:
25 
26- **Global API Key** (Recommended): Full access to all entities across your Rootly instance. Required for organization-wide visibility across teams, schedules, and incidents.
27- **Team API Key**: Team Admin permissions with full read/edit access to entities owned by that team. Suitable for team-specific workflows.
28- **Personal API Key**: Inherits the permissions of the user who created it. Works for individual use cases but may have limited visibility.
29 
30For full functionality of tools like `get_oncall_handoff_summary`, `get_oncall_shift_metrics`, and organization-wide incident search, a **Global API Key** is recommended.
31 
32## Quick Start
33 
34The fastest way to get started is to connect to our hosted MCP server — no installation required, just add the configuration to your editor:
35 
36```json
37{
38  "mcpServers": {
39    "rootly": {
40      "url": "https://mcp.rootly.com/sse",
41      "headers": {
42        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
43      }
44    }
45  }
46}
47```
48 
49For **Claude Code**, run:
50 
51```bash
52claude mcp add rootly --transport sse https://mcp.rootly.com/sse \
53  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"
54```
55 
56## Alternative Installation (Local)
57 
58If you prefer to run the MCP server locally, configure your editor with one of the options below. The package will be automatically downloaded and installed when you first open your editor.
59 
60### With uv
61 
62```json
63{
64  "mcpServers": {
65    "rootly": {
66      "command": "uv",
67      "args": [
68        "tool",
69        "run",
70        "--from",
71        "rootly-mcp-server",
72        "rootly-mcp-server"
73      ],
74      "env": {
75        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
76      }
77    }
78  }
79}
80```
81 
82### With uvx
83 
84```json
85{
86  "mcpServers": {
87    "rootly": {
88      "command": "uvx",
89      "args": [
90        "--from",
91        "rootly-mcp-server",
92        "rootly-mcp-server"
93      ],
94      "env": {
95        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
96      }
97    }
98  }
99}
100```
101 
102## Features
103 
104- **Dynamic Tool Generation**: Automatically creates MCP resources from Rootly's OpenAPI (Swagger) specification
105- **Smart Pagination**: Defaults to 10 items per request for incident endpoints to prevent context window overflow
106- **API Filtering**: Limits exposed API endpoints for security and performance
107- **Intelligent Incident Analysis**: Smart tools that analyze historical incident data
108  - **`find_related_incidents`**: Uses TF-IDF similarity analysis to find historically similar incidents
109  - **`suggest_solutions`**: Mines past incident resolutions to recommend actionable solutions
110- **MCP Resources**: Exposes incident and team data as structured resources for easy AI reference
111- **Intelligent Pattern Recognition**: Automatically identifies services, error types, and resolution patterns
112- **On-Call Health Integration**: Detects workload health risk in scheduled responders
113 
114## On-Call Health Integration
115 
116Rootly MCP integrates with [On-Call Health](https://oncallhealth.ai) to detect workload health risk in scheduled responders.
117 
118### Setup
119 
120Set the `ONCALLHEALTH_API_KEY` environment variable:
121 
122```json
123{
124  "mcpServers": {
125    "rootly": {
126      "command": "uvx",
127      "args": ["rootly-mcp-server"],
128      "env": {
129        "ROOTLY_API_TOKEN": "your_rootly_token",
130        "ONCALLHEALTH_API_KEY": "och_live_your_key"
131      }
132    }
133  }
134}
135```
136 
137### Usage
138 
139```
140check_oncall_health_risk(
141    start_date="2026-02-09",
142    end_date="2026-02-15"
143)
144```
145 
146Returns at-risk users who are scheduled, recommended safe replacements, and action summaries.
147 
148## Example Skills
149 
150Want to get started quickly? We provide pre-built Claude Code skills that showcase the full power of the Rootly MCP server:
151 
152### 🚨 [Rootly Incident Responder](examples/skills/rootly-incident-responder.md)
153 
154An AI-powered incident response specialist that:
155- Analyzes production incidents with full context
156- Finds similar historical incidents using ML-based similarity matching
157- Suggests solutions based on past successful resolutions
158- Coordinates with on-call teams across timezones
159- Correlates incidents with recent code changes and deployments
160- Creates action items and remediation plans
161- Provides confidence scores and time estimates
162 
163**Quick Start:**
164```bash
165# Copy the skill to your project
166mkdir -p .claude/skills
167cp examples/skills/rootly-incident-responder.md .claude/skills/
168 
169# Then in Claude Code, invoke it:
170# @rootly-incident-responder analyze incident #12345
171```
172 
173This skill demonstrates a complete incident response workflow using Rootly's intelligent tools combined with GitHub integration for code correlation.
174 
175### On-Call Shift Metrics
176 
177Get on-call shift metrics for any time period, grouped by user, team, or schedule. Includes primary/secondary role tracking, shift counts, hours, and days on-call.
178 
179```
180get_oncall_shift_metrics(
181    start_date="2025-10-01",
182    end_date="2025-10-31",
183    group_by="user"
184)
185```
186 
187### On-Call Handoff Summary
188 
189Complete handoff: current/next on-call + incidents during shifts.
190 
191```python
192# All on-call (any timezone)
193get_oncall_handoff_summary(
194    team_ids="team-1,team-2",
195    timezone="America/Los_Angeles"
196)
197 
198# Regional filter - only show APAC on-call during APAC business hours
199get_oncall_handoff_summary(
200    timezone="Asia/Tokyo",
201    filter_by_region=True
202)
203```
204 
205Regional filtering shows only people on-call during business hours (9am-5pm) in the specified timezone.
206 
207Returns: `schedules` with `current_oncall`, `next_oncall`, and `shift_incidents`
208 
209### Shift Incidents
210 
211Incidents during a time period, with filtering by severity/status/tags.
212 
213```python
214get_shift_incidents(
215    start_time="2025-10-20T09:00:00Z",
216    end_time="2025-10-20T17:00:00Z",
217    severity="critical",  # optional
218    status="resolved",    # optional
219    tags="database,api"   # optional
220)
221```
222 
223Returns: `incidents` list + `summary` (counts, avg resolution time, grouping)
224 
225 
226## Contributing
227 
228See [CONTRIBUTING.md](CONTRIBUTING.md) for developer setup and guidelines.
229 
230## Play with it on Postman
231[<img src="https://run.pstmn.io/button.svg" alt="Run In Postman" style="width: 128px; height: 32px;">](https://god.gw.postman.com/run-collection/45004446-1074ba3c-44fe-40e3-a932-af7c071b96eb?action=collection%2Ffork&source=rip_markdown&collection-url=entityId%3D45004446-1074ba3c-44fe-40e3-a932-af7c071b96eb%26entityType%3Dcollection%26workspaceId%3D4bec6e3c-50a0-4746-85f1-00a703c32f24)
232 
233 
234## About Rootly AI Labs
235 
236This project was developed by [Rootly AI Labs](https://labs.rootly.ai/), where we're building the future of system reliability and operational excellence. As an open-source incubator, we share ideas, experiment, and rapidly prototype solutions that benefit the entire community.
237![Rootly AI logo](https://github.com/Rootly-AI-Labs/EventOrOutage/raw/main/rootly-ai.png)
238 
239 
240