mcp-uptime-kuma

mcp-uptime-kuma

适用于 Uptime Kuma version 2 的 Model Context Protocol (MCP) 服务。支持 stdio 和 streamable HTTP 传输方式。

功能

• 实时监控：通过 Socket.IO 访问监控项、心跳、运行时间和响应能力指标，并即时接收状态变更通知。
• 适合上下文：默认仅返回必要数据，避免大模型上下文窗口负担过重。
• 多种传输方式：支持 stdio（本地）和 streamable HTTP（远程）传输方式。

快速开始

使用 npx（stdio 传输方式）

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

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "npx",
      "args": ["-y", "@davidfuchs/mcp-uptime-kuma@latest"],
      "env": {
        "UPTIME_KUMA_URL": "http://your-uptime-kuma-instance:3001",
        "UPTIME_KUMA_USERNAME": "your_username",
        "UPTIME_KUMA_PASSWORD": "your_password"
      }
    }
  }
}

请保留 @latest 后缀。若不保留，npx 会重复使用首次运行时缓存的版本，无法获取新版本。

使用 Docker（streamable HTTP 传输方式）

选项 1：Docker Run

docker run -d \
  --name mcp-uptime-kuma \
  -p 3000:3000 \
  -e UPTIME_KUMA_URL=http://your-uptime-kuma-instance:3001 \
  -e UPTIME_KUMA_USERNAME=your_username \
  -e UPTIME_KUMA_PASSWORD=your_password \
  davidfuchs/mcp-uptime-kuma:latest \
  -t streamable-http

选项 2：Docker Compose

仓库中提供了 docker-compose.yml 文件。下载该文件，配置环境变量，然后运行：

docker compose up -d

然后配置 MCP 客户端连接到此端点：

{
  "mcpServers": {
    "uptime-kuma": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

有关 JWT 令牌和匿名身份验证选项，请参阅身份验证方式。

上述端点未经过身份验证。 任何能够访问端口 3000 的人都可以完全读写你的 Uptime Kuma 实例。将其暴露到 localhost 之外之前，请参阅 保护 HTTP 端点。

对话示例

在 LibreChat 中的对话，mcp-uptime-kuma 服务正在提供 Uptime Kuma 的实时信息。

可用工具

监控项

工具	用途
getMonitorSummary	快速概览所有监控项及其当前状态。支持筛选。
listMonitors	获取所有监控项的完整列表及其配置。支持筛选。
listMonitorTypes	获取 Uptime Kuma 支持的所有可用监控项类型。
getMonitor	根据 ID 获取特定监控项的详细配置。
createMonitor	创建新的监控项（至少需要名称和类型）。
updateMonitor	更新现有监控项的配置。
deleteMonitor	永久删除监控项及其所有心跳历史记录。
pauseMonitor	暂停监控项，停止执行检查。
resumeMonitor	恢复已暂停的监控项，重新开始检查。

心跳

工具	用途
listHeartbeats	获取所有监控项的状态检查历史记录。
getHeartbeats	获取特定监控项的状态检查历史记录。

通知

工具	用途
listNotifications	列出所有已配置的通知渠道（Slack、Discord、电子邮件、webhook 等）。
addNotification	创建新的通知渠道。
updateNotification	更新现有的通知渠道。
deleteNotification	永久删除通知渠道。

标签

工具	用途
listTags	列出 Uptime Kuma 中定义的所有标签。
addTag	创建可分配给监控项的新标签。
deleteTag	永久删除标签（并将其从所有监控项中移除）。

维护

工具	用途
getMaintenanceWindows	列出所有维护窗口，以及每个窗口覆盖的监控项。
createMaintenance	安排新的维护窗口，并添加要抑制通知的监控项。
updateMaintenance	更改维护窗口的计划、详情或监控项列表。
pauseMaintenance	关闭维护窗口（结束手动维护窗口）。
resumeMaintenance	重新开启已暂停的维护窗口（启动手动维护窗口）。
deleteMaintenance	永久删除维护窗口。

状态页和设置

工具	用途
listStatusPages	列出所有已配置的状态页。
getSettings	获取 Uptime Kuma 服务设置。

筛选

getMonitorSummary 和 listMonitors 支持按以下条件筛选：

• keywords：以空格分隔的关键词，用于模糊匹配监控项的 pathNames
• type：监控项类型，多个类型以逗号分隔（例如，"http"、"http,ping,dns"）
• active：按监控项是否处于活动状态筛选（true 表示活动，false 表示非活动）
• maintenance：按维护模式状态筛选
• tags：标签名称和可选值，以逗号分隔（例如，"production"、"env=staging"）
• parentId：分组监控项 ID，返回该分组的直接子项。传入 null 可获取顶层监控项（没有父级的监控项）。不会递归；若要深入遍历，请使用每个子分组自己的 childrenIDs。
• status（仅限 getMonitorSummary）：心跳状态（"0"=DOWN，"1"=UP，"2"=PENDING，"3"=MAINTENANCE）

示例：

getMonitorSummary({ status: "0" })                     // All DOWN monitors
getMonitorSummary({ type: "http", maintenance: true }) // HTTP monitors in maintenance
getMonitorSummary({ parentId: 12, status: "0" })       // What's down inside group 12
listMonitors({ tags: "production,region=us-east" })    // Monitors with specific tags
listMonitors({ parentId: 12 })                         // Direct children of group 12
listMonitors({ parentId: null })                       // Top-level monitors only

身份验证方法

匿名身份验证

如果你的 Uptime Kuma 实例已禁用身份验证，则只需设置 UPTIME_KUMA_URL。

用户名/密码身份验证

UPTIME_KUMA_URL=http://your-instance:3001
UPTIME_KUMA_USERNAME=your_username
UPTIME_KUMA_PASSWORD=your_password
UPTIME_KUMA_2FA_TOKEN=123456  # Optional, only if 2FA is enabled

JWT 令牌身份验证

推荐用于启用了双重身份验证的用户。如果同时提供 JWT 令牌和用户名/密码，优先使用 JWT 令牌。

UPTIME_KUMA_URL=http://your-instance:3001
UPTIME_KUMA_JWT_TOKEN=your_jwt_token

获取 JWT 令牌

使用 CLI 工具（推荐）：

npx -p @davidfuchs/mcp-uptime-kuma@latest mcp-uptime-kuma-get-jwt http://localhost:3001 admin mypassword

使用 Docker：

docker run --rm davidfuchs/mcp-uptime-kuma:latest get-jwt http://host.docker.internal:3001 admin mypassword

**从浏览器获取：**打开开发者工具 → 存储/应用程序 → 本地存储 → 找到 token 键。

位于需要身份验证的代理之后（Cloudflare Access 等）

如果 Uptime Kuma 位于需要自身凭据的代理之后——例如 Cloudflare Zero Trust Access 应用、oauth2-proxy 或 API 网关——请将 UPTIME_KUMA_HEADERS 设置为一个 JSON 对象，其中包含要随每个请求发送的标头。它可以与上述任意方法组合使用；这些方法仍负责登录 Uptime Kuma 本身。

对于 Cloudflare Access，请创建服务令牌，并为允许该令牌的应用添加 Service Auth 策略，然后：

UPTIME_KUMA_URL=https://uptime.example.com
UPTIME_KUMA_HEADERS={"CF-Access-Client-Id":"<client-id>.access","CF-Access-Client-Secret":"<client-secret>"}
UPTIME_KUMA_USERNAME=your_username
UPTIME_KUMA_PASSWORD=your_password

在 MCP 客户端的 JSON 配置中，该值是一个字符串，因此需要转义其中的引号：

"UPTIME_KUMA_HEADERS": "{\"CF-Access-Client-Id\":\"<client-id>.access\",\"CF-Access-Client-Secret\":\"<client-secret>\"}"

mcp-uptime-kuma-get-jwt 会读取相同的变量。如果值格式错误，服务会在启动时停止，并报告出错的标头名称；标头值绝不会被记录。

保护 HTTP 端点

仅适用于 -t streamable-http。stdio 传输没有需要保护的监听器，其凭据取自环境变量，正如 MCP 规范所规定的那样。

任何能够访问 /mcp 的人都可以完全读写你的 Uptime Kuma 实例，包括删除监控项。有两个设置可以保护它们，且默认都较为宽松，以免升级破坏现有部署——处于这种状态时，服务会在启动时发出警告。

变量	默认值	用途
MCP_AUTH_TOKEN	未设置（无身份验证）	调用方必须通过 Authorization: Bearer <token> 提供的共享密钥。其他任何值都会收到 401。
ALLOWED_ORIGIN	*（不验证）	允许调用 /mcp 的浏览器来源，以逗号分隔。Origin 不在列表中的请求会收到 403。没有 Origin 标头的请求（所有原生 MCP 客户端）始终允许通过。
HOST	0.0.0.0	绑定地址。在容器外本地运行时，设置为 127.0.0.1。
PORT	3000	监听端口。
TRUST_PROXY	未设置（不信任）	信任服务前方反向代理提供的 X-Forwarded-For，使速率限制器使用真实客户端 IP，而不是代理的 IP。可接受跳数（1）、true/false 或 IP/子网列表——请参阅 Express 的 trust proxy 文档。

/health 特意不进行身份验证，以确保容器健康检查和负载均衡器探测正常工作。它只报告服务是否存活。

设置令牌

生成高熵密钥——它就是一个密码，并且会通过恒定时间比较，因此只有长度能保护它：

openssl rand -base64 32

docker run -d \
  --name mcp-uptime-kuma \
  -p 3000:3000 \
  -e UPTIME_KUMA_URL=http://your-uptime-kuma-instance:3001 \
  -e UPTIME_KUMA_JWT_TOKEN=your_jwt_token \
  -e MCP_AUTH_TOKEN=your_generated_secret \
  davidfuchs/mcp-uptime-kuma:latest \
  -t streamable-http

然后，客户端通过标头发送它：

{
  "mcpServers": {
    "uptime-kuma": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your_generated_secret"
      }
    }
  }
}

为什么需要单独验证 Origin

共享密钥可以阻止无法提供该密钥的人，但无法阻止浏览器已信任的网站。在 DNS 重绑定攻击中，evil.example 上的页面会将自己的主机名解析到 127.0.0.1，于是浏览器会将发往本地服务的请求视为同源请求——不会进行预检，CORS 也不会生效。服务将收到的 Origin 标头与预期来源列表进行比对，是唯一仍然有效的检查；这也是 MCP 规范将其列为 MUST 而非 SHOULD 的原因。

如果你只使用原生客户端，不设置 ALLOWED_ORIGIN 不会带来任何影响；这些客户端不会发送 Origin 标头。如果你使用基于浏览器的客户端，请列出其来源：

ALLOWED_ORIGIN=https://librechat.example.com,http://localhost:5173

在反向代理后运行

如果不设置 TRUST_PROXY，Express 会认为每个请求都来自代理的 IP，因此速率限制器会将所有客户端放进同一个共享的 100 次请求额度中；当任何客户端的请求累计达到上限时，就会开始错误地返回 429。

将 TRUST_PROXY 设置为服务前方的代理跳数，以便它从 X-Forwarded-For 读取真实客户端 IP：

TRUST_PROXY=1

只有在你控制的代理确实会移除并重新设置该标头时，才设置此项。如果服务也可以直接访问，或者代理会透传收到的任何 X-Forwarded-For，客户端就可以伪造该标头，让每个请求都获得一个新的速率限制额度，从而完全绕过限制器。

凭据脱敏

读取工具会以 *** 替代机密，而不是返回其值。

Uptime Kuma 的 socket API 会原样返回配置，而其 Web 界面会在渲染时隐藏凭据。这对浏览器来说没问题，但对 MCP 服务来说不行，因为其输出会进入大模型的上下文窗口，随后保存在对话记录、日志和同步历史记录中。询问“我在监控什么？”不应该把有效的 SMTP 密码或第三方 API 密钥写入你可能无法控制的存储中。

隐藏的内容如下：

工具	隐藏内容
listNotifications	config 中除 type/name/isDefault/applyExisting 之外的所有内容。隐藏的字段名称列在 redactedConfigKeys 中
listMonitors、getMonitor	pushToken、basic_auth_pass、bearer_token、oauth_client_secret、radiusPassword、radiusSecret、mqttPassword、rabbitmqPassword、tlsCert/tlsKey/tlsCa、databaseConnectionString、headers、grpcMetadata，以及任何匹配 `/pass
listDockerHosts	dockerDaemon URL 中的 user:password@
getHeartbeats、listHeartbeats	Uptime Kuma 返回的超出声明心跳字段范围的任何列（例如可能包含服务响应正文的 response）都会被丢弃；状态消息中引用的 URL 内的 user:password@ 也会被清除
getSettings	Uptime Kuma 返回的任何名称中包含机密字样的字段（例如 steamAPIKey）
getMonitorSummary	无——它一开始就不会返回凭据

hostname、port、url、authMethod、oauth_token_url、oauth_scopes 和用户名仍会显示：隐藏有用的配置只会让脱敏功能被关闭。

要获取实际值，可以在调用时传入 includeSecrets: true：

listNotifications({ includeSecrets: true })

也可以全局启用：

UPTIME_KUMA_INCLUDE_SECRETS=true

在两种情况下，单次调用参数的优先级都高于环境变量，因此即使在允许显示机密的部署中，也仍可让某次调用进行脱敏。

写回 *** 是安全的。 updateMonitor 和 updateNotification 会在字段值为该标记时恢复已存储的值，并报告保留了哪些字段。这对 updateNotification 尤为重要：Uptime Kuma 会替换通知记录，而不是合并记录；如果没有这项保护，读取、编辑再写回就会把有效密码替换为三个星号。如果没有可恢复的已存储值，调用会失败，而不是写入一个看似已设置、实际却无法使用的凭据。

updateDockerHost 对嵌入 dockerDaemon URL 的凭据也有同样的保护：从 listDockerHosts 读回的 http://***:***@host:2375 会从已存储的 URL 中恢复用户信息，而不是原样持久化。因此，无需重新输入凭据即可更改主机指向，而不会清除凭据。

MCP 日志通道也遵循同一规则。对于实时心跳，调试日志只会报告被监控服务状态消息的长度（msgLength=...），绝不会记录其内容，因为该消息可能会回显嵌入 user:password@ 的目标 URL，或响应正文的一部分；在 stdio 传输中，这些日志通知会到达客户端。

LibreChat 配置

stdio 传输：

mcpServers:
  uptime-kuma:
    command: npx
    args: ["-y", "@davidfuchs/mcp-uptime-kuma@latest"]
    env:
      UPTIME_KUMA_URL: "http://your-instance:3001"
      UPTIME_KUMA_USERNAME: "your_username"
      UPTIME_KUMA_PASSWORD: "your_password"
    serverInstructions: true

streamable HTTP 传输：

将允许的域名更新为 URL 中使用的域名（例如，Docker 环境中的 localhost 或 host.docker.internal）：

mcpServers:
  uptime-kuma:
    type: streamable-http
    url: "http://mcp-uptime-kuma:3000/mcp"
    serverInstructions: true

mcpSettings:
  allowedDomains:
    - 'mcp-uptime-kuma'

参与贡献

有关开发环境设置、构建、测试和项目结构，请参阅 CONTRIBUTING.md。

了解更多

• Uptime Kuma
• Model Context Protocol 文档
• MCP TypeScript SDK
• MCP 规范

安全

如需报告漏洞，请参阅 SECURITY.md。

免责声明

这是一个个人免费开源的业余项目，按“现状”提供，并受 MIT 许可证约束，不附带任何形式的保证。您需要自行安装和运行此项目，它会连接到您控制的 Uptime Kuma 实例。作者不对因使用本项目而产生的任何损失、数据丢失、停机或其他后果负责。使用风险由您自行承担。

许可证

根据 MIT 许可证授权。