healthchecks-mcp

# healthchecks-mcp

<!-- badges: start -->

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/healthchecks-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/healthchecks-mcp/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/healthchecks-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/healthchecks-mcp)
<a href="https://socket.dev/npm/package/healthchecks-mcp"><img src="https://socket.dev/api/badge/npm/package/healthchecks-mcp" alt="Socket supply-chain report" height="20"></a>
[![Glama score](https://glama.ai/mcp/servers/ni-c/healthchecks-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/healthchecks-mcp)
<br>
[![npm version](https://img.shields.io/npm/v/healthchecks-mcp)](https://www.npmjs.com/package/healthchecks-mcp)
[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fhealthchecks--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/healthchecks-mcp/pkgs/container/healthchecks-mcp)
[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
<br>
[![docs](https://img.shields.io/badge/docs-healthchecks--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://healthchecks-mcp.ni-c.de)
[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
<!-- badges: end -->

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
[Healthchecks](https://healthchecks.io), the dead man's switch for cron jobs and
scheduled tasks — it alerts you when a job stops checking in. Works against the
hosted service and against a self-hosted instance alike.

Lets MCP clients like Claude Code, Claude Desktop or Codex see which scheduled
jobs are healthy, read the output the failing one reported, and create or adjust
checks — with the irreversible operations behind a confirmation token and the
write tools switchable off entirely.

Fourteen tools is the ceiling, not the floor:
`HEALTHCHECKS_ALLOW_TOOLS=essential` registers a curated seven instead, and a
model picks the right tool far more reliably from seven than from fourteen — see
[choosing which tools load](#choosing-which-tools-load).

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://healthchecks-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://healthchecks-mcp.ni-c.de/architecture-light.svg">
  <img src="https://healthchecks-mcp.ni-c.de/architecture.svg" alt="An MCP client talks to healthchecks-mcp over stdio; the server calls the Healthchecks Management API v3 over HTTPS." width="800">
</picture>

![Listing the tools, narrowing them to the essential preset, and the startup abort a mistyped tool name produces](https://healthchecks-mcp.ni-c.de/demo.gif)

## What makes it different

**It reads the ping bodies.** `get_ping_body` returns what a job actually printed
when it reported failure. Every other question — which check is down, since when,
how often — is one step away from that one, and it is the endpoint the other
Healthchecks MCP servers leave out.

**Read-only API keys work properly.** Healthchecks hands a read-only key a
different object: no `uuid`, no `ping_url`, no `channels` — a 40-character
`unique_key` instead. This server addresses checks by either, and
`get_api_key_info` tells you up front which kind of key you configured and which
tools it cannot reach, rather than leaving you with a `401 missing api key` for a
key that was sent.

**It never pings a check.** Pinging is how a job reports that it ran. A tool that
could ping would let a model make a dead job look alive, which is the one thing
monitoring must not allow — see [Not exposed, on purpose](#not-exposed-on-purpose).

**It knows where this API is sharp.** `timeout` and `schedule` cannot be combined
because the upstream silently discards one of them; tags are validated against
their space separator and keywords against their comma; a new check is given
every integration unless you say otherwise, because the API's own default is a
check that alerts nobody.

## Requirements

- Node.js ≥ 22
- A **Healthchecks** project API key — Project Settings → API Access. Keys are per
  project, not per account, and are exactly 32 characters long.

## Configuration

| Variable                    | Required | Description                                                                                           |
| --------------------------- | -------- | ----------------------------------------------------------------------------------------------------- |
| `HEALTHCHECKS_API_KEY`      | yes      | Project API key. A read-only key works for part of the tool surface — see below                       |
| `HEALTHCHECKS_URL`          | no       | Site root of a self-hosted instance, e.g. `https://hc.example.net`. Default `https://healthchecks.io` |
| `HEALTHCHECKS_READ_ONLY`    | no       | `true` registers only the read tools                                                                  |
| `HEALTHCHECKS_ALLOW_TOOLS`  | no       | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset                    |
| `HEALTHCHECKS_DENY_TOOLS`   | no       | Same syntax; removed from whatever `HEALTHCHECKS_ALLOW_TOOLS` left                                    |
| `HEALTHCHECKS_INSECURE_TLS` | no       | `true` accepts self-signed certificates (scoped to this connection)                                   |
| `ELICITATION`               | no       | `false` replaces the approval dialog with the two-call token. **Not prefixed**                        |

`HEALTHCHECKS_URL` is the site root, not the API root: `https://hc.example.net`,
not `https://hc.example.net/api/v3`. Both are accepted — the suffix is trimmed —
because the API documentation spells every example the long way.

> **Use `https://`.** Over plain http the API key travels unencrypted; the server
> prints a warning unless the host is local. For self-signed certificates prefer a
> proper internal CA over `HEALTHCHECKS_INSECURE_TLS`.

Without an API key the server still starts and lists its tools (so registries and
inspectors can introspect it), but every call except `get_status` fails with setup
instructions instead of reaching the API.

**Read-only keys.** Healthchecks gates three tools that only read — `list_pings`,
`get_ping_body` and `list_integrations` — behind a read-write key anyway. With a
read-only key those fail, along with all five write tools.

The failure does not look like a permission problem: the API answers
`401 {"error": "wrong api key"}`, which reads as if the key were wrong or
missing. It is not — those three tools translate it into what actually happened.
`get_api_key_info` reports which kind of key is configured, and
`HEALTHCHECKS_DENY_TOOLS` is the tidy way to stop offering them at all.

### Choosing which tools load

`HEALTHCHECKS_ALLOW_TOOLS` and `HEALTHCHECKS_DENY_TOOLS` take comma-separated tool
names; a trailing `*` matches a whole family. `essential` is a curated preset —
`list_checks`, `get_check`, `list_pings`, `list_flips`, `create_check`,
`update_check` and `resume_check` — marked as such in the
[tool reference](https://healthchecks-mcp.ni-c.de/reference/tools).

```sh
HEALTHCHECKS_ALLOW_TOOLS=essential
HEALTHCHECKS_ALLOW_TOOLS=list_*,get_check
HEALTHCHECKS_DENY_TOOLS=delete_check,pause_check
```

An entry that matches no tool aborts startup and names it, so a typo cannot silently
hide a tool — an absent tool is not something anyone traces back to an environment
variable. A filtered tool is never registered, so it is absent from `tools/list` and
unknown to `tools/call` alike, exactly like a write tool under
`HEALTHCHECKS_READ_ONLY`.

If you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de) is
the other answer — its `/hub` endpoint replaces every server's tools with six
meta-tools.

## Installation

### Claude Code

```sh
claude mcp add healthchecks-mcp -- npx -y healthchecks-mcp
```

### Claude Desktop

```json
{
  "mcpServers": {
    "healthchecks-mcp": {
      "command": "npx",
      "args": ["-y", "healthchecks-mcp"],
      "env": {
        "HEALTHCHECKS_API_KEY": "…"
      }
    }
  }
}
```

### Codex

```toml
[mcp_servers.healthchecks-mcp]
command = "npx"
args = ["-y", "healthchecks-mcp"]
env = { HEALTHCHECKS_API_KEY = "…" }
```

### Docker

```sh
docker run --rm -i \
  -e HEALTHCHECKS_API_KEY=… \
  ghcr.io/ni-c/healthchecks-mcp
```

Add `-e HEALTHCHECKS_URL=https://hc.example.net` for a self-hosted instance.

### Through mcp-hub

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web,
Cursor, LibreChat — reaches healthchecks-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one
container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login
behind a single password and long-lived tokens for the clients that cannot do OAuth. Its
`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of
them without N×tool schemas in the model's context, and it speaks both protocol revisions
— a question this server asks travels through it to the person at the far end.

Its `/config/mcp.json` uses Claude Code's format, so the entry is the one you already
have:

```json
{
  "mcpServers": {
    "healthchecks-mcp": {
      "command": "npx",
      "args": ["-y", "healthchecks-mcp"],
      "env": {
        "HEALTHCHECKS_URL": "https://hc.example.net",
        "HEALTHCHECKS_API_KEY": "…",
        "HEALTHCHECKS_ALLOW_TOOLS": "essential"
      },
      "denyTools": ["delete_check,pause_check"]
    }
  }
}
```

`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not
the same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,
are in the [client guide](https://healthchecks-mcp.ni-c.de/guide/clients#through-mcp-hub)