# Instatus MCP Server

[![CI](https://github.com/OfirOhan/instatus-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/OfirOhan/instatus-mcp/actions/workflows/ci.yml)
![MCP](https://img.shields.io/badge/MCP-compatible-blue)
![License: MIT](https://img.shields.io/badge/license-MIT-green)

A [Model Context Protocol](https://modelcontextprotocol.io) server for **[Instatus](https://instatus.com)**. It lets Claude, Cursor, ChatGPT and other AI agents check what's down, open and update incidents, flip component statuses and schedule maintenance on your status page, straight from the chat or terminal where the on-call engineer is already working.

> **Unofficial.** This is a community project and is not affiliated with Instatus. It was built from Instatus's public API docs.

## What you can ask your agent

- "Is anything on our status page degraded right now? Summarize any open incidents."
- "Open an incident on the **API** component: elevated 5xx errors, we're investigating. Don't notify subscribers yet."
- "Post an update on that incident: root cause identified, a fix is rolling out. Mark the API as degraded instead of partial outage."
- "We're back. Resolve the incident and set everything to operational."
- "Schedule a 45-minute database maintenance window for Sunday 02:00 UTC on **API** and **Dashboard**."

## Tools

| Tool | What it does | Writes? |
|---|---|---|
| `get_current_user` | Who owns this API key | No |
| `list_status_pages` | Your pages with id, subdomain and public URL | No |
| `get_status_overview` | **One-call "is anything down?"**: overall state, components by status, open incidents with latest update, upcoming maintenance | No |
| `list_components` / `get_component` | Components and their current status | No |
| `list_incidents` / `get_incident` | Incidents with their update timeline, filterable by status | No |
| `list_maintenances` | Scheduled, in-progress and past maintenance | No |
| `set_component_status` | Change one component's status without an incident | Yes |
| `create_incident` | Open an incident and set the impact on affected components | Yes |
| `post_incident_update` | Add a public update, optionally changing component impact | Yes |
| `resolve_incident` | Post a RESOLVED update and set affected components back to OPERATIONAL in one step | Yes |
| `schedule_maintenance` | Announce a maintenance window (auto start/end, components shown as under maintenance) | Yes |
| `delete_incident` | Delete an incident | **Destructive** |

Design notes:

- **Subscribers are not notified by default.** Every write tool takes `notify`, which defaults to `false`, so an agent can't email your customers unless you ask it to.
- `get_status_overview` pulls components, unresolved incidents and maintenances in parallel and returns a short summary instead of three raw API dumps.
- `resolve_incident` and `post_incident_update` look up the incident's components for you, so the agent doesn't need to track component IDs between turns.
- All tools carry MCP annotations (`readOnlyHint`, `destructiveHint`), so clients can ask before publishing anything.

## Setup

1. Create an API key in Instatus: **User settings → Developer settings**.
2. Build it:

```bash
git clone https://github.com/OfirOhan/instatus-mcp.git
cd instatus-mcp && npm install && npm run build
```

### Claude Desktop

Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "instatus": {
      "command": "node",
      "args": ["/absolute/path/to/instatus-mcp/dist/index.js"],
      "env": { "INSTATUS_API_KEY": "your-api-key" }
    }
  }
}
```

### Claude Code / Cursor / other MCP clients

```bash
claude mcp add instatus -e INSTATUS_API_KEY=your-api-key -- node /path/to/instatus-mcp/dist/index.js
```

For Cursor and other clients, use the same command with `INSTATUS_API_KEY` in the environment.

| Variable | Default | Notes |
|---|---|---|
| `INSTATUS_API_KEY` | (required) | Your Instatus API key |
| `INSTATUS_BASE_URL` | `https://api.instatus.com` | Override for testing |

## Development

```bash
npm install
npm test   # builds, runs unit tests and an end-to-end MCP stdio test against a fake Instatus API
```

The tests run on Node 20, 22 and 24 in CI.

## Author

Built by [Ofir Ohana](https://github.com/OfirOhan), an AI agents engineer. Issues and PRs are welcome.

## License

MIT