用自然语言管理监控:Kuvasz MCP服务器接入Claude与Cursor的完整教程

原创2026-11-04 19:44:541,939 阅读

用自然语言管理监控:Kuvasz MCP服务器接入Claude与Cursor的完整教程

Kuvasz 是一款开源的 uptime 与 SSL 监控服务,而从 4.0 版本起,它内置了 MCP(Model Context Protocol)服务器,让 AI 助手可以直接"看懂"并操作你的监控系统。完成本文的 Kuvasz MCP 服务器接入教程后,你就可以在 Claude、Cursor 或任何支持 MCP 的客户端里,用一句自然语言完成"列出所有宕机的监控"、"创建一个新的 HTTP 监控"这样的操作——不用再打开仪表盘手动点了。

Kuvasz Uptime 项目横幅

⚠️ 注意: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 传输方式。

Kuvasz 仪表盘


二、开启 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 小时有延迟飙升?"

Kuvasz 延迟与事故图表


四、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 工具完成创建。

Kuvasz 监控详情页面


五、常用自然语言指令示例

接入完成后,以下是几类典型玩法(工具支持按名称搜索、分页、排序,列表默认每页 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 助手管理:

  1. ✅ Cursor 用户:直连 /mcp 端点 + 请求头鉴权,3 分钟完成;
  2. ✅ Claude 用户:加一层 npx mcp-remote 桥接即可,零全局安装;
  3. ✅ 查询、创建、切换、删改事故备注,全部一句话搞定。

配合 Kuvasz 原有的 REST API、Prometheus 指标导出与 YAML IAC 支持,MCP 让它成为目前对 AI 工具链最友好的开源监控方案之一。

📚 延伸阅读:MCP 服务器功能文档 · 完整配置参考 · MCP 工具源码 mcp/

登录后查看全文
kuvasz