Healthchecks

healthchecks-mcp

一个面向 Healthchecks 的 Model Context Protocol（MCP）服务。Healthchecks 是用于 cron 作业和计划任务的“死人开关”——当作业停止签到时，它会发出警报。既可连接托管服务，也可连接可自托管实例。

让 Claude Code、Claude Desktop 或 Codex 等 MCP 客户端查看哪些计划作业运行正常、读取故障作业报告的输出，以及创建或调整检查项——不可逆操作须使用确认令牌，并且可以彻底关闭写入工具。

工具数量的上限是 14 个，而非最低要求： HEALTHCHECKS_ALLOW_TOOLS=essential 会改为注册精心挑选的 7 个工具。与 14 个相比，模型从 7 个工具中选出合适工具要可靠得多——请参阅选择加载哪些工具。

与众不同之处

它会读取 ping 的正文。 get_ping_body 会返回任务报告失败时实际输出的内容。其他问题——哪个检查出现故障、从什么时候开始、发生了多少次——都只需多走一步就能找到答案，而这正是其他 Healthchecks MCP 服务所缺少的端点。

只读 API 密钥也能正常使用。 Healthchecks 为只读密钥提供不同的对象：没有 uuid、ping_url、channels，而是提供一个 40 个字符的 unique_key。此服务可以通过任一标识访问检查；get_api_key_info 会预先告知你配置的是哪种密钥，以及它无法访问哪些工具，而不是让你面对一个已发送密钥却仍返回 401 missing api key 的错误。

它绝不会 ping 检查。 Ping 是任务报告自己已运行的方式。允许 ping 的工具会让模型把一个已停止运行的任务伪装成正常运行，而监控绝不能允许这种情况——请参阅刻意不提供的功能。

它了解此 API 的陷阱。 timeout 和 schedule 不能同时使用，因为上游会悄悄丢弃其中一个；标签会根据空格分隔符进行验证，关键词则会根据逗号进行验证；除非你另有说明，否则新建的检查会默认启用所有集成，因为 API 自身的默认设置是无人收到告警。

要求

• Node.js ≥ 22
• 一个 Healthchecks 项目 API 密钥——Project Settings → API Access。密钥按项目而非账户分配，且长度恰好为 32 个字符。

配置

变量	必需	描述
HEALTHCHECKS_API_KEY	是	项目 API 密钥。只读密钥可用于部分工具，详见下文
HEALTHCHECKS_URL	否	自托管实例的站点根 URL，例如 https://hc.example.net。默认值为 https://healthchecks.io
HEALTHCHECKS_READ_ONLY	否	true 仅注册读取工具
HEALTHCHECKS_ALLOW_TOOLS	否	以逗号分隔的工具名称、list_* 前缀，或用于精选预设的 essential
HEALTHCHECKS_DENY_TOOLS	否	语法相同；从 HEALTHCHECKS_ALLOW_TOOLS 留下的工具中移除
HEALTHCHECKS_INSECURE_TLS	否	true 接受自签名证书（仅对此连接生效）
ELICITATION	否	false 会将审批对话框替换为双调用令牌。不带前缀

HEALTHCHECKS_URL 是站点根 URL，而不是 API 根 URL：应为 https://hc.example.net， 而非 https://hc.example.net/api/v3。两种写法都可接受——后缀会被去掉—— 因为 API 文档中的示例都采用了较长的写法。

请使用 https://。 使用普通 http 时，API 密钥会以未加密的形式传输；除非主机位于本地，否则服务器 会打印警告。对于自签名证书，建议使用正规的内部 CA，而不是 HEALTHCHECKS_INSECURE_TLS。

没有 API 密钥时，服务器仍会启动并列出其工具（以便注册表和检查器进行检查），但除 get_status 外， 所有调用都会返回设置说明，而不会访问 API。

只读密钥。 Healthchecks 会强制要求使用读写密钥，才能调用三个仅读取数据的工具——list_pings、 get_ping_body 和 list_integrations。使用只读密钥时，这些工具以及全部五个写入工具都会调用失败。

失败信息看起来不像权限问题：API 返回 401 {"error": "wrong api key"}，读起来仿佛密钥错误或缺失。实际并非如此——这三个工具会将该错误转换为 实际发生情况的说明。get_api_key_info 会报告已配置的密钥类型，而使用 HEALTHCHECKS_DENY_TOOLS 则可以简洁地停止提供这些工具。

选择要加载的工具

HEALTHCHECKS_ALLOW_TOOLS 和 HEALTHCHECKS_DENY_TOOLS 接受以逗号分隔的工具名称； 末尾的 * 可匹配整个工具系列。essential 是一个精选预设，包含 list_checks、get_check、list_pings、list_flips、create_check、 update_check 和 resume_check，并在工具参考中标注为预设。

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

如果某个条目未匹配任何工具，启动会中止并指出该条目，因此拼写错误不会悄悄隐藏工具——没有人会追溯 一个缺失的工具是否由环境变量造成。经过筛选的工具不会注册，因此它们既不会出现在 tools/list 中， 也无法通过 tools/call 调用；这与 HEALTHCHECKS_READ_ONLY 下的写入工具完全相同。

如果你同时运行多个此类服务，mcp-hub 是另一种解决方案——它的 /hub 端点会用六个元工具替换每个服务的所有工具。

安装

Claude Code

claude mcp add healthchecks-mcp -- npx -y healthchecks-mcp

Claude Desktop

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

Codex

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

Docker

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

对于自托管实例，请添加 -e HEALTHCHECKS_URL=https://hc.example.net。

通过 mcp-hub

无法启动本地进程的客户端——ChatGPT connectors、Web 版 Claude、Cursor、LibreChat——可通过 mcp-hub 访问 healthchecks-mcp：一个容器通过 Streamable HTTP 为多个 stdio MCP 服务提供服务，并通过单个密码进行 OAuth 2.1 登录，还为无法使用 OAuth 的客户端提供长期有效的令牌。其 /hub 端点通过六个元工具连接每个服务，因此一个连接器就能访问所有服务，而无需在模型上下文中放入 N×工具的架构；它还同时支持两个协议版本——此服务提出的问题会经由它传递给远端的用户。

其 /config/mcp.json 使用 Claude Code 的格式，因此配置项就是你已有的那一项：

{
  "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 和 denyTools 是 hub 自己针对每个服务的筛选器，与 env 中的 *_ALLOW_TOOLS 并不相同——两者的区别以及容易因此犯下的错误，详见客户端指南。

工具

始终会注册读取工具。🔑 表示 Healthchecks 要求使用读写密钥才能调用的工具，尽管它们只执行读取操作；👤 表示执行操作前需要确认令牌的工具。

工具	描述
list_checks	项目中的检查，支持按 tag、slug 和 status 筛选
get_check	按 UUID 或 unique_key 获取包含所有字段的单个检查
list_pings 🔑	某个检查最近的 ping，按时间从新到旧排列
get_ping_body 🔑	作业随某个 ping 发送的 POST 正文——其输出
list_flips	某个检查的正常/故障状态转换，支持指定时间范围
list_integrations 🔑	通知集成，以及写入工具接受的 UUID
list_badges	状态徽章 URL，按标签和项目划分
get_status	实例是否可访问——完全不需要 API 密钥
get_api_key_info	实例、密钥类型，以及该密钥无法执行的操作

除非设置了 HEALTHCHECKS_READ_ONLY=true，否则会注册写入工具。

工具	描述
create_check	创建检查。除非 channels 另有指定，否则会通知每个集成
update_check	更改指定字段。channels 会替换列表，而不是追加；不允许使用空列表
pause_check	停止等待 ping 的检查——并停止告警。resume_check 会将其恢复
resume_check	将已暂停的检查恢复到 new 状态
delete_check 👤	删除检查。UUID 无法恢复

结构化输出

每个工具都会声明一个 outputSchema，并在文本块旁通过 structuredContent 返回结果，因此客户端无需解析文字说明即可使用结果：

{
  "untrusted": true,
  "source": "healthchecks",
  "checks": [{ "id": "…", "name": "Nightly Backup", "status": "up" }],
  "total_in_project": 12,
}

每个会报告实例信息的工具都会携带 untrusted: true 和 source: "healthchecks" 字段——检查名称、描述，尤其是记录的 ping 正文，都是由发送 ping 的人编写的；而 ping URL 则位于每台受监控主机的 cron 作业中。get_api_key_info 不携带这些字段；get_status 仅在实例返回的内容不是 OK 时才携带这些字段：纯粹的 OK 是此服务自己的说法，而对所有内容都标记，就等于标记什么也没标记。

此服务构建的字段都有精确定义；检查记录则保持开放，因为 normalizeCheck 会原样传递可自托管版本选择添加的内容，而 SDK 会在返回每个结果前根据其架构进行验证。

有意不提供的功能

• 发送 ping。 服务从不调用 ping URL。发送 ping 是作业报告其已运行的方式；如果某个工具能发送 ping，那么模型——或模型读取的文本——就能为实际上未执行的作业报告成功；而一个能被说服显示绿色状态的监控系统，还不如没有。
• Ping 密钥。 无法通过 Management API 读取这些密钥，此服务也不会请求密钥。
• 创建集成。 API 没有用于创建集成的端点；集成需要在 Web UI 中配置。list_integrations 用于读取集成。
• 将 unique upsert 作为默认行为。 create_check 接受此选项，并会在结果中明确说明已使用该选项，因为它会把创建操作变成对已存在检查的静默更新。

安全

• delete_check 会征求用户确认。 如果客户端支持 MCP elicitation，就会弹出一个模型无法代为回答的实际对话框；如果不支持，则会改用一个仅短暂有效、绑定到特定检查和特定操作的令牌，并明确说明这一点，而不会让人误以为已有人批准。 pause_check 则刻意不征求确认——resume_check 可以恢复检查，中间不会丢失任何内容；而在可撤销的更改前设置对话框，会让人学会不看内容就点确认。请参阅 征求用户确认。
• 确认提示词绝不会引用来自 Healthchecks 的内容——检查名称和描述是此服务无法控制的自由文本，而模型会读取这些文本。
• Ping 正文和检查描述都会标记为不可信数据，因为任何能发送 ping 的人都能向其中写入内容。
• 错误正文会被截断，HTML 错误页面会被丢弃，并且会在流式传输期间对每个响应强制执行字节数上限——Management API 不会对任何内容进行分页。
• HEALTHCHECKS_READ_ONLY=true 完全不会注册写入工具；HEALTHCHECKS_DENY_TOOLS 则可以按相同原则进行更精细的限制——被筛除的工具根本不会构建，而不是在调用时被拒绝。
• API 密钥读取后会从 process.env 中删除，并且绝不会放进请求正文中传输。

文档

完整指南、工具参考和安全说明请见 healthchecks-mcp.ni-c.de（源文件位于 docs/）。

开发

npm install
npm run lint && npm run build && npm run test:coverage

发布

1. 添加 CHANGELOG 条目并更新 package.json 中的版本。
2. npm run lint && npm run build && npm run test:coverage
3. 提交，然后推送签名标签：git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z

发布工作流会将软件包发布到 npm（使用 Trusted Publishing，并附带来源证明）、根据 CHANGELOG 条目创建 GitHub 发布，并更新 MCP Registry 条目。

贡献

欢迎提交问题、参与讨论和发起拉取请求——请参阅 CONTRIBUTING.md。如需报告漏洞，请使用 私密报告渠道， 而不要公开提交问题；相关政策见 SECURITY.md。

许可证

MIT © Willi Thiel