mcp-server-health-monitor

MCP 服务健康监控

npm mcp-server-health-monitor 包

原生支持 MCP 协议的健康监控，而不仅仅是 HTTP 监控。它不会对端口执行 ping，而是对每个服务调用 list_tools——这与 Agent 使用的握手方式相同——因此，绿色状态意味着服务确实已准备好处理 MCP 请求。所有健康记录都保存在本地 SQLite 中；无需外部监控服务。

工具参考 | 配置 | 参与贡献 | 故障排除

主要功能

• 自动发现：读取现有的 MCP 配置文件（Claude Desktop、Cursor、VS Code），无需额外设置。
• 非侵入式探测：仅对目标服务调用 list_tools——只读操作，不产生副作用。
• 版本差异检测：比较不同检查中的工具架构，以检测服务是否已更新。
• 历史趋势：将延迟历史记录存储在 SQLite 中；根据已存储的历史记录按需计算 p50/p95，以便在问题演变为故障前发现性能回退。
• HTML 仪表板：生成独立的健康仪表板，其中包含每个服务的运行时间迷你趋势图。
• 后台轮询：作为守护进程运行，确保在你请求时健康数据始终是最新的。

为什么选择它，而不是通用运行时间监控工具？

通用运行时间监控工具（UptimeRobot、Pingdom、BetterStack）会检查端口是否开放，或 HTTP 端点是否返回 200。对于 MCP 服务来说，这还不够——服务可能正在运行，却无法完成 MCP 协议协商，或返回错误的工具架构。

	mcp-server-health-monitor	通用运行时间监控工具
探测方式	调用 MCP list_tools——测试实际协议	HTTP ping 或 TCP 端口检查
架构差异检测	检测不同版本间的工具签名变化	不了解协议则无法实现
自动发现配置	自动读取 Claude Desktop、Cursor、VS Code 配置	手动为每个服务输入 URL
数据驻留	本地 SQLite；无需外部服务	健康数据存储在供应商云端
费用	免费，可自托管	免费套餐有限；历史记录/警报需付费

如果你想确认 MCP 服务确实运行正常，而不只是“进程正在运行”，这就是合适的工具。

要求

• Node.js v20.19 或更高版本。
• npm。

开始使用

将以下配置添加到 MCP 客户端：

{
  "mcpServers": {
    "health-monitor": {
      "command": "npx",
      "args": ["-y", "mcp-server-health-monitor@latest"]
    }
  }
}

监控器会从注册该监控器的同一配置文件中自动发现其他 MCP 服务。无需额外设置。

MCP 客户端配置

Amp · Claude Code · Cline · Cursor · VS Code · Windsurf · Zed

你的第一个提示词

在 MCP 客户端中输入以下内容，以验证一切正常：

Check the health of all my MCP servers.

客户端应返回一个状态表，显示每个服务的当前延迟和健康状态。

工具

健康检查（3 个工具）

• health_check_all — 通过 list_tools 并行探测所有已配置的服务，测量延迟并存储结果。可选参数 timeout_ms（默认值：5000）。
• get_server_status — 返回每个服务的详细信息，包括延迟、最后发现时间、24 小时错误数、最后一条错误消息，以及 p50/p95 延迟百分位数。需要提供 server_name。
• list_degraded — 筛选离线或延迟超过阈值的服务。可选参数 latency_threshold 用于覆盖默认阈值。

历史记录（1 个工具）

• get_history — 返回指定服务的原始健康检查历史记录，按时间从近到远排序。需要提供 server_name；可选参数 limit（默认值：50，最大值：500）。

服务注册表（2 个工具）

• configure_server — 注册新的 MCP 服务进行监控。以此方式添加的服务会存储在 ~/.mcp/extra-servers.json 中，并与自动发现的服务合并。必需参数：name、command。可选参数：args、env。
• remove_server — 从监控中移除手动注册的服务。仅影响通过 configure_server 添加的服务；不会影响自动发现的服务。需要提供 name。

更新（1 个工具）

• check_updates — 在每次探测时通过对工具架构进行哈希计算并与上次存储的哈希进行比较，检测版本差异。针对每个服务返回 has_changed、previous_hash、current_hash 和 changed_at。

导出（1 个工具）

• export_dashboard — 生成独立的单文件 HTML 仪表板，包含摘要卡片、带 p50/p95 延迟的各服务状态表，以及内嵌的 SVG 正常运行时间迷你图。可选择使用 output_path 将文件写入磁盘。

手动服务注册表

除了从 MCP 配置文件自动发现服务外，你还可以使用 configure_server 工具注册未包含在 Claude Desktop 配置中的服务。手动注册的服务会写入 ~/.mcp/extra-servers.json（与健康数据库存放在同一位置），并在每次探测时与自动发现的服务合并。

Add a server named "my-internal-tool" running with command "node" and args ["/opt/tools/server.js"]

如需停止监控手动注册的服务：

Remove the server named "my-internal-tool" from monitoring

通过 Claude Desktop 配置发现的服务无法使用 remove_server 移除；请直接编辑 MCP 配置文件来移除这些服务。

配置

--interval / --interval-seconds

轮询每个 MCP 服务的频率，单位为秒。

类型：number 默认值：60

--latency-threshold

超过此毫秒数后，服务会被标记为性能下降。

类型：number 默认值：1000

--db / --db-path

用于存储健康历史记录的 SQLite 数据库文件路径。

类型：string 默认值：~/.mcp/health.db

--daemon

作为后台轮询守护进程运行。健康数据将持续收集，而非按需收集。

类型：boolean 默认值：false

--startup-grace-seconds

新启动的服务在被判定为不健康前的宽限时间，单位为秒。

类型：number 默认值：10

通过 JSON 配置中的 args 属性传递标志：

{
  "mcpServers": {
    "health-monitor": {
      "command": "npx",
      "args": ["-y", "mcp-server-health-monitor@latest", "--interval=30", "--latency-threshold=500"]
    }
  }
}

收录平台

• 已收录于 MCP Registry — 搜索 mcp-server-health-monitor。
• 已收录于 MCP Market — 搜索 mcp-server-health-monitor。

验证

发布新版本前，请使用 MCP Inspector 验证服务，确认所有工具均已正确暴露且协议握手成功。

交互式 UI（打开浏览器）：

npm run build && npm run inspect

CLI 模式（支持脚本 / CI）：

# List all tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

# List resources and prompts
npx @modelcontextprotocol/inspector --cli node dist/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node dist/index.js --method prompts/list

# Call a tool (example — replace with a relevant read-only tool for this plugin)
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name health_check_all

# Call a tool with arguments
npx @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name health_check_all --tool-arg key=value

发布前运行，以发现工具注册和运行时启动方面的回归问题。

贡献

探测模块位于 src/probes/。每个探测都必须返回一个包含 status、latencyMs 和可选 message 的 ProbeResult。所有探测都必须保持只读——绝不要在受监控的服务上触发副作用。

npm install && npm test