用自然语言管理监控:Kuvasz MCP服务器接入Claude与Cursor的完整教程
用自然语言管理监控:Kuvasz MCP服务器接入Claude与Cursor的完整教程
Kuvasz 是一款开源的 uptime 与 SSL 监控服务,而从 4.0 版本起,它内置了 MCP(Model Context Protocol)服务器,让 AI 助手可以直接"看懂"并操作你的监控系统。完成本文的 Kuvasz MCP 服务器接入教程后,你就可以在 Claude、Cursor 或任何支持 MCP 的客户端里,用一句自然语言完成"列出所有宕机的监控"、"创建一个新的 HTTP 监控"这样的操作——不用再打开仪表盘手动点了。
⚠️ 注意:MCP 服务器目前仍是实验性功能,工具名称和参数结构可能在后续版本中变化。官方说明见 mcp-server.md。
一、Kuvasz 的 MCP 服务器是什么?
MCP 是 Anthropic 提出的一种开放协议,用于让 AI 客户端(如 Claude Desktop、Cursor)安全地调用外部工具。Kuvasz 把它的监控数据和管理操作封装成一个个 MCP 工具(tools) 暴露出来,例如:
| 你想做的事 | 对应的 MCP 工具 |
|---|---|
| 查看所有 HTTP 监控的运行状态 | list-http-monitors |
| 查看某监控的延迟统计 | get-http-monitor-stats |
| 新建一个 TCP 端口监控 | create-tcp-monitor |
| 列出所有事故并查看详情 | list-incidents / get-incident-details |
| 给事故添加排查备注 | create-incident-note |
| 创建计划内维护窗口 | create-maintenance-window |
覆盖 HTTP、ICMP、Push(心跳)、TCP、DNS、Docker 六种监控类型,外加状态页、维护窗口、集成通知和事故管理。完整工具清单可以在 mcp-server.md 中查看,工具名常量定义在 Constants.kt 里。
启用后,服务器会出现在你 Kuvasz 实例的 /mcp 端点(如 https://your.kuvasz.host/mcp),使用 MCP 规范定义的 Streamable HTTP 传输方式。
二、开启 MCP 服务器的两步配置
MCP 服务器默认是关闭的,需要两项配置(参考 configuration.md):
第 1 步:开启 MCP 服务器
YAML 配置方式:
micronaut.mcp.server.enabled: true
环境变量方式:
ENABLE_MCP_SERVER=true
第 2 步:设置独立的 MCP API Key
这是新手最容易踩的坑:/mcp 端点使用的是一把独立的 MCP API key,与 REST API 的 key 互不相通——即使你的 REST API key 有效,也不能访问 MCP 端点。
YAML 配置方式:
admin-auth.mcp-api-key: ThisShouldBeVeryVerySecureToo
环境变量方式:
ADMIN_MCP_API_KEY=ThisShouldBeVeryVerySecureToo
两个注意点:
- 🔑 Key 长度至少 16 个字符,否则 Kuvasz 会拒绝启动;
- 认证支持两种传法:请求头
X-API-KEY: 你的Key,或Authorization: Bearer 你的Key; - 如果你完全禁用了认证,MCP 端点也随之免认证(仅限内网可信环境使用)。
三、Cursor 接入:直连 /mcp 端点
Cursor 原生支持 Streamable HTTP 传输,因此不需要任何中间件,直接在 Cursor 的 MCP 设置中添加服务器即可(Cursor → Settings → MCP → Add Server):
{
"mcpServers": {
"kuvasz-uptime": {
"url": "https://your.kuvasz.host/mcp",
"headers": {
"X-API-KEY": "{{ Your API key }}"
}
}
}
}
保存后,Cursor 会自动拉取工具列表。在聊天或 Agent 模式下直接用中文提问即可,例如:
"帮我看看哪些 HTTP 监控最近 24 小时有延迟飙升?"
四、Claude 接入:用 mcp-remote 搭建本地桥
Claude Desktop 这类客户端只走 STDIO 传输,不能直连 HTTP 端点。解决办法很轻量:用 npm 生态的 mcp-remote 桥接工具做本地转译,通过 npx 运行即可,无需全局安装任何依赖。
在 Claude 的配置文件(claude_desktop_config.json)中加入:
{
"mcpServers": {
"kuvasz-uptime": {
"command": "npx",
"args": [
"mcp-remote",
"https://your.kuvasz.host/mcp",
"--header",
"X-API-KEY: {{ Your API key }}"
]
}
}
}
重启 Claude 后,在对话框里直接说:
"帮我创建一个针对 1.1.1.1 的 ICMP 监控,名字叫 ping-check"
Claude 就会自动调用 create-icmp-monitor 工具完成创建。
五、常用自然语言指令示例
接入完成后,以下是几类典型玩法(工具支持按名称搜索、分页、排序,列表默认每页 25 条):
📊 状态查询类
- "列出所有宕机的监控,按名称排序"
- "查一下 push 心跳监控 my-cron-job 最近 7 天的可用率统计"
- "状态页
status现在有哪些监控是红色的?"(调用get-status-page-details)
🛠 创建与切换类
- "通过代理
eu-proxy创建一个 HTTP 监控,检查 https://shop.example.com,期望状态码 200" - "把 ICMP 监控
router-192-168-1-1暂停一下,今晚维护" - "给支付服务建一个每周日凌晨 2 点到 4 点的 cron 维护窗口"
🚨 事故处理类
- "最近 24 小时有哪些未解决的事故?把详情和已通知的集成发给我"
- "给 5 分钟前那次 SSL 到期事故加一条备注:已收到续期邮件,明天处理"
六、使用须知:只读模式与分页机制
🔒 YAML 只读模式
如果你的监控是通过 YAML 声明式配置的(IaC 用户),对应的 create-*、toggle-*、delete-* 工具会直接返回错误——这与你在 REST API 或仪表盘里做同样操作的结果完全一致。查询类工具(list-*、get-*-details、get-*-stats、list-incidents 等)则始终可用。事故备注永远不受 YAML 只读限制。
📄 分页返回
所有列表工具一次只返回一页(默认 25 条),结果中会带上总条目数和总页数,AI 助手会自动用 page 参数翻页,无需你干预。
🧩 Docker 主机与代理
Docker 主机和出站代理只能通过 YAML 配置,MCP 端只能列出(list-docker-hosts、list-proxies),不能创建。不过 AI 助手可以先查列表,再把名称填进 create-docker-monitor 的 dockerHost 字段或 create-http-monitor 的 proxy 字段。
七、常见问题排查
| 症状 | 原因与解决 |
|---|---|
401 / 403 认证失败 |
确认用的是 MCP API key 而非 REST API key;检查请求头拼写(X-API-KEY) |
| Kuvasz 启动失败 | MCP API key 长度不足 16 个字符 |
| 创建监控返回只读错误 | 该监控类型由 YAML 管理,请改用 list-* 查询,或从 YAML 中移除该配置 |
| Cursor 连不上 | 确认填写的是完整 /mcp URL,且实例支持 Streamable HTTP |
| Claude 工具列表为空 | npx mcp-remote 首次运行需下载依赖,检查网络后重试 |
总结
只需两步配置(ENABLE_MCP_SERVER=true + ADMIN_MCP_API_KEY),Kuvasz 的 MCP 服务器就能把六种监控类型、事故、状态页和维护窗口全部交给你的 AI 助手管理:
- ✅ Cursor 用户:直连
/mcp端点 + 请求头鉴权,3 分钟完成; - ✅ Claude 用户:加一层
npx mcp-remote桥接即可,零全局安装; - ✅ 查询、创建、切换、删改事故备注,全部一句话搞定。
配合 Kuvasz 原有的 REST API、Prometheus 指标导出与 YAML IAC 支持,MCP 让它成为目前对 AI 工具链最友好的开源监控方案之一。
📚 延伸阅读:MCP 服务器功能文档 · 完整配置参考 · MCP 工具源码 mcp/



