Metadata-Version: 2.4
Name: rootly-mcp-server
Version: 2.2.11
Summary: Secure Model Context Protocol server for Rootly APIs with AI SRE capabilities, comprehensive error handling, and input validation
Project-URL: Homepage, https://github.com/Rootly-AI-Labs/Rootly-MCP-server
Project-URL: Issues, https://github.com/Rootly-AI-Labs/Rootly-MCP-server/issues
Author-email: Rootly AI Labs <support@rootly.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-sre,automation,devops,incident-management,incidents,llm,mcp,on-call,rate-limiting,rootly,security,sre
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Requires-Dist: brotli>=1.2.0
Requires-Dist: fastmcp[code-mode]==3.1.0
Requires-Dist: httpx==0.28.1
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic==2.12.5
Requires-Dist: requests==2.32.5
Requires-Dist: scikit-learn>=1.3.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: black>=26.3.1; extra == 'dev'
Requires-Dist: isort>=5.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pip-audit>=2.7.0; extra == 'dev'
Requires-Dist: types-requests>=2.32.0; extra == 'dev'
Description-Content-Type: text/markdown

<!-- mcp-name: com.rootly/mcp-server -->
# Rootly MCP Server

[![PyPI version](https://badge.fury.io/py/rootly-mcp-server.svg)](https://pypi.org/project/rootly-mcp-server/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/rootly-mcp-server)](https://pypi.org/project/rootly-mcp-server/)
[![Python Version](https://img.shields.io/pypi/pyversions/rootly-mcp-server.svg)](https://pypi.org/project/rootly-mcp-server/)
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=rootly&config=eyJ1cmwiOiJodHRwczovL21jcC5yb290bHkuY29tL3NzZSIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8WU9VUl9ST09UTFlfQVBJX1RPS0VOPiJ9fQ==)

An 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.

![Demo GIF](https://raw.githubusercontent.com/Rootly-AI-Labs/Rootly-MCP-server/refs/heads/main/rootly-mcp-server-demo.gif)

## Quick Start

The fastest way to get started is to connect to our hosted MCP server — no installation required.

### Claude Code

```bash
claude mcp add --transport http rootly https://mcp.rootly.com/mcp \
  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"
```

Code Mode:

```bash
claude mcp add rootly-codemode --transport http https://mcp.rootly.com/mcp-codemode \
  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"
```

SSE fallback:

```bash
claude mcp add --transport sse rootly-sse https://mcp.rootly.com/sse \
  --header "Authorization: Bearer YOUR_ROOTLY_API_TOKEN"
```

### Gemini CLI

Install the extension:

```bash
gemini extensions install https://github.com/Rootly-AI-Labs/Rootly-MCP-server
```

Or configure manually in `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "rootly": {
      "command": "uvx",
      "args": ["--from", "rootly-mcp-server", "rootly-mcp-server"],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json` or `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "rootly": {
      "url": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
```

### Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "rootly": {
      "serverUrl": "https://mcp.rootly.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
```

### Codex

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.rootly]
url = "https://mcp.rootly.com/mcp"
bearer_token_env_var = "ROOTLY_API_TOKEN"
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rootly": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.rootly.com/mcp",
        "--header",
        "Authorization: Bearer <YOUR_ROOTLY_API_TOKEN>"
      ]
    }
  }
}
```

## Rootly CLI

We also offer a standalone CLI for managing incidents, alerts, services, on-call schedules, and more directly from your terminal.

Install via Homebrew:

```bash
brew install rootlyhq/tap/rootly-cli
```

Or via Go:

```bash
go install github.com/rootlyhq/rootly-cli/cmd/rootly@latest
```

For more details, see the [Rootly CLI repository](https://github.com/rootlyhq/rootly-cli).

## Alternative Installation (Local)

If 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.

### Prerequisites

- Python 3.12 or higher
- `uv` package manager
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
- [Rootly API token](https://docs.rootly.com/api-reference/overview#how-to-generate-an-api-key%3F) with appropriate permissions (see below)

### API Token Permissions

The MCP server requires a Rootly API token. Choose the appropriate token type based on your needs:

- **Global API Key** (Recommended): Full access to all entities across your Rootly instance. Required for organization-wide visibility across teams, schedules, and incidents.
- **Team API Key**: Team Admin permissions with full read/edit access to entities owned by that team. Suitable for team-specific workflows.
- **Personal API Key**: Inherits the permissions of the user who created it. Works for individual use cases but may have limited visibility.

For full functionality of tools like `get_oncall_handoff_summary`, `get_oncall_shift_metrics`, and organization-wide incident search, a **Global API Key** is recommended.

### With uv

```json
{
  "mcpServers": {
    "rootly": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "rootly-mcp-server",
        "rootly-mcp-server"
      ],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
```

## Self-Hosted Transport Options

Choose one transport per server process:

- **Streamable HTTP** endpoint path: `/mcp`
- **SSE** endpoint path: `/sse`
- **Code Mode (experimental)** endpoint path: `/mcp-codemode` in hosted dual-transport mode. Set `ROOTLY_CODE_MODE_ENABLED=false` to disable it or `ROOTLY_CODE_MODE_PATH` to customize the path.

Example Docker run (Streamable HTTP):

```bash
docker run -p 8000:8000 \
  -e ROOTLY_TRANSPORT=streamable-http \
  -e ROOTLY_API_TOKEN=<YOUR_ROOTLY_API_TOKEN> \
  rootly-mcp-server
```

Example Docker run (SSE):

```bash
docker run -p 8000:8000 \
  -e ROOTLY_TRANSPORT=sse \
  -e ROOTLY_API_TOKEN=<YOUR_ROOTLY_API_TOKEN> \
  rootly-mcp-server
```

Example Docker run (Dual transport + Code Mode):

```bash
docker run -p 8000:8000 \
  -e ROOTLY_TRANSPORT=both \
  -e ROOTLY_API_TOKEN=<YOUR_ROOTLY_API_TOKEN> \
  rootly-mcp-server
```

### With uvx

```json
{
  "mcpServers": {
    "rootly": {
      "command": "uvx",
      "args": [
        "--from",
        "rootly-mcp-server",
        "rootly-mcp-server"
      ],
      "env": {
        "ROOTLY_API_TOKEN": "<YOUR_ROOTLY_API_TOKEN>"
      }
    }
  }
}
```

## Features

- **Dynamic Tool Generation**: Automatically creates MCP resources from Rootly's OpenAPI (Swagger) specification
- **Smart Pagination**: Defaults to 10 items per request for incident endpoints to prevent context window overflow
- **API Filtering**: Limits exposed API endpoints for security and performance
- **Intelligent Incident Analysis**: Smart tools that analyze historical incident data
  - **`find_related_incidents`**: Uses TF-IDF similarity analysis to find historically similar incidents
  - **`suggest_solutions`**: Mines past incident resolutions to recommend actionable solutions
- **MCP Resources**: Exposes incident and team data as structured resources for easy AI reference
- **Intelligent Pattern Recognition**: Automatically identifies services, error types, and resolution patterns
- **On-Call Health Integration**: Detects workload health risk in scheduled responders

## Supported Tools

The default server configuration currently exposes **101 tools** (including custom agentic tools and OpenAPI-generated tools).

### Custom Agentic Tools

- `check_oncall_health_risk`
- `check_responder_availability`
- `create_override_recommendation`
- `find_related_incidents`
- `getIncident` - retrieve a single incident for direct verification, including PIR-related fields
- `get_alert_by_short_id`
- `get_oncall_handoff_summary`
- `get_oncall_schedule_summary`
- `get_oncall_shift_metrics`
- `get_server_version`
- `get_shift_incidents`
- `list_endpoints`
- `list_shifts`
- `search_incidents`
- `suggest_solutions`
- `updateIncident` - scoped incident update tool for `summary` and `retrospective_progress_status`

### OpenAPI-Generated Tools

```text
attachAlert
createAlert
createEnvironment
createEscalationLevel
createEscalationLevelPaths
createEscalationPath
createEscalationPolicy
createFunctionality
createIncidentActionItem
createIncidentType
createOnCallRole
createOnCallShadow
createOverrideShift
createSchedule
createScheduleRotation
createScheduleRotationActiveDay
createScheduleRotationUser
createService
createSeverity
createTeam
createWorkflow
deleteEscalationLevel
deleteEscalationPath
deleteEscalationPolicy
deleteSchedule
deleteScheduleRotation
getAlert
getCurrentUser
getEnvironment
getEscalationLevel
getEscalationPath
getEscalationPolicy
getFunctionality
getIncidentType
getOnCallRole
getOnCallShadow
getOverrideShift
getSchedule
getScheduleRotation
getScheduleShifts
getService
getSeverity
getTeam
getUser
getWorkflow
listAlerts
listEnvironments
listEscalationLevels
listEscalationLevelsPaths
listEscalationPaths
listEscalationPolicies
listFunctionalities
listIncidentActionItems
listIncidentAlerts
listIncident_Types
listOnCallRoles
listOnCallShadows
listOverrideShifts
listScheduleRotationActiveDays
listScheduleRotationUsers
listScheduleRotations
listSchedules
listServices
listSeverities
listShifts
listTeams
listUsers
listWorkflows
updateAlert
updateEnvironment
updateEscalationLevel
updateEscalationPath
updateEscalationPolicy
updateFunctionality
updateIncidentType
updateOnCallRole
updateOnCallShadow
updateOverrideShift
updateSchedule
updateScheduleRotation
updateService
updateSeverity
updateTeam
updateUser
updateWorkflow
```

Delete operations are intentionally scoped to screenshot coverage paths:
`deleteSchedule`, `deleteScheduleRotation`, `deleteEscalationPolicy`, `deleteEscalationPath`, `deleteEscalationLevel`.

## On-Call Health Integration

Rootly MCP integrates with [On-Call Health](https://oncallhealth.ai) to detect workload health risk in scheduled responders.

### Setup

Set the `ONCALLHEALTH_API_KEY` environment variable:

```json
{
  "mcpServers": {
    "rootly": {
      "command": "uvx",
      "args": ["rootly-mcp-server"],
      "env": {
        "ROOTLY_API_TOKEN": "your_rootly_token",
        "ONCALLHEALTH_API_KEY": "och_live_your_key"
      }
    }
  }
}
```

### Usage

```
check_oncall_health_risk(
    start_date="2026-02-09",
    end_date="2026-02-15"
)
```

Returns at-risk users who are scheduled, recommended safe replacements, and action summaries.

## Example Skills

Want to get started quickly? We provide pre-built Claude Code skills that showcase the full power of the Rootly MCP server:

### 🚨 [Rootly Incident Responder](examples/skills/rootly-incident-responder.md)

An AI-powered incident response specialist that:
- Analyzes production incidents with full context
- Finds similar historical incidents using ML-based similarity matching
- Suggests solutions based on past successful resolutions
- Coordinates with on-call teams across timezones
- Correlates incidents with recent code changes and deployments
- Creates action items and remediation plans
- Provides confidence scores and time estimates

**Quick Start:**
```bash
# Copy the skill to your project
mkdir -p .claude/skills
cp examples/skills/rootly-incident-responder.md .claude/skills/

# Then in Claude Code, invoke it:
# @rootly-incident-responder analyze incident #12345
```

This skill demonstrates a complete incident response workflow using Rootly's intelligent tools combined with GitHub integration for code correlation.

### On-Call Shift Metrics

Get 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.

```
get_oncall_shift_metrics(
    start_date="2025-10-01",
    end_date="2025-10-31",
    group_by="user"
)
```

### On-Call Handoff Summary

Complete handoff: current/next on-call + incidents during shifts.

```python
# All on-call (any timezone)
get_oncall_handoff_summary(
    team_ids="team-1,team-2",
    timezone="America/Los_Angeles"
)

# Regional filter - only show APAC on-call during APAC business hours
get_oncall_handoff_summary(
    timezone="Asia/Tokyo",
    filter_by_region=True
)
```

Regional filtering shows only people on-call during business hours (9am-5pm) in the specified timezone.

Returns: `schedules` with `current_oncall`, `next_oncall`, and `shift_incidents`

### Shift Incidents

Incidents during a time period, with filtering by severity/status/tags.

```python
get_shift_incidents(
    start_time="2025-10-20T09:00:00Z",
    end_time="2025-10-20T17:00:00Z",
    severity="critical",  # optional
    status="resolved",    # optional
    tags="database,api"   # optional
)
```

Returns: `incidents` list + `summary` (counts, avg resolution time, grouping)


## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for developer setup and guidelines.

## Play with it on Postman
[<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)


## About Rootly AI Labs

This 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.
![Rootly AI logo](https://github.com/Rootly-AI-Labs/EventOrOutage/raw/main/rootly-ai.png)
