mcp-uptime-kuma

一个用于Uptime Kuma 版本2 的Model Context Protocol (MCP)服务器。支持标准输入输出（stdio）和可流式传输的HTTP传输。

功能

• Uptime Kuma 集成：通过Socket.IO连接实时访问Uptime Kuma的监控器、心跳、正常运行时间和响应度指标。此MCP服务器会在Uptime Kuma的状态发生变化时立即收到通知，并缓存这些信息以实现快速检索。
• 上下文友好：谨慎控制返回的数据量，避免压垮LLM上下文窗口。工具默认只返回必要的字段和最近的心跳记录，需要时可以请求更多数据。
• 多种传输方式：支持标准输入输出（stdio，用于本地集成）和可流式传输的HTTP（用于远程访问）。

可用工具

工具	目的
getMonitorSummary	获取所有监控器及其当前状态的快速概览
getMonitor	根据ID获取特定监控器的详细配置
listMonitors	获取所有监控器及其配置的完整列表
getHeartbeats	获取特定监控器的状态检查历史
listHeartbeats	获取所有监控器的状态检查历史
getSettings	获取Uptime Kuma服务器设置

示例对话

在LibreChat中的对话，其中mcp-uptime-kuma服务器提供了来自Uptime Kuma的实时信息。

快速开始

大多数用户会希望使用标准输入输出（stdio）来配置mcp-uptime-kuma，如下所示。

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

如果您的Uptime Kuma实例禁用了身份验证，您可以移除用户名/密码环境变量。有关身份验证方法的更多细节，请参阅使用说明部分。

使用说明

前提条件

• Node.js（v18或更高版本）
• 一个Uptime Kuma实例（版本2）

身份验证方法

此MCP服务器支持三种连接到您的Uptime Kuma实例的身份验证方法。

关于双因素认证（2FA）的注意事项：如果您正在使用2FA，建议您直接采用JWT身份验证方法，避免使用用户名/密码身份验证，因为您的2FA令牌每次初始化MCP服务器时都需要刷新。

即使使用JWT方法，您也可能遇到令牌过期的问题，但截至本文撰写时，Uptime Kuma返回的JWT似乎不会过期。

1. 匿名身份验证

如果您的Uptime Kuma实例禁用了身份验证，您可以无需提供任何凭证即可连接。只需UPTIME_KUMA_URL环境变量即可。

• 必需变量：
  • UPTIME_KUMA_URL：您的Uptime Kuma实例的URL

2. 用户名/密码身份验证

使用您的Uptime Kuma凭证的标准身份验证。此方法使用UPTIME_KUMA_USERNAME和UPTIME_KUMA_PASSWORD环境变量。

• 必需变量：

  • UPTIME_KUMA_URL：您的Uptime Kuma实例的URL
  • UPTIME_KUMA_USERNAME：您的Uptime Kuma用户名
  • UPTIME_KUMA_PASSWORD：您的Uptime Kuma密码

• 可选变量：

  • UPTIME_KUMA_2FA_TOKEN：您的2FA令牌（仅当您的账户启用了两步验证时才需要）

3. JWT令牌身份验证

基于从Uptime Kuma获取的JWT令牌的身份验证。此方法使用UPTIME_KUMA_JWT_TOKEN环境变量，并且如果同时提供了用户名/密码，则优先使用JWT令牌。

• 必需变量：
  • UPTIME_KUMA_URL：您的Uptime Kuma实例的URL
  • UPTIME_KUMA_JWT_TOKEN：您的JWT令牌（请参阅下面的说明以了解如何获取它）

如何找到您的JWT令牌：

1. 在您的网络浏览器中登录到您的Uptime Kuma实例
2. 打开浏览器的开发者工具（F12或右键点击→检查）
3. 导航到存储标签（Firefox）或应用标签（Chrome/Edge）
4. 在本地存储或会话存储下，找到您的Uptime Kuma域
5. 查找名为token的键——其值就是您的JWT令牌（应以'ey...'开头）
6. 复制令牌值并将其用作UPTIME_KUMA_JWT_TOKEN

使用标准输入输出（stdio）传输设置mcp-uptime-kuma

对于许多MCP客户端，您可以按照以下方式配置服务器：

选项1：用户名/密码身份验证

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

选项2：JWT令牌身份验证

{
  "mcpServers": {
    "uptime-kuma": {
      "command": "npx",
      "args": ["-y", "@davidfuchs/mcp-uptime-kuma"],
      "env": {
        "UPTIME_KUMA_URL": "http://your-uptime-kuma-instance:3001",
        "UPTIME_KUMA_JWT_TOKEN": "your_jwt_token"
      }
    }
  }
}

请参阅如何找到您的JWT令牌部分以获取说明。

如果您使用的是LibreChat（librechat.yaml），可以这样配置：

选项1：用户名/密码身份验证（LibreChat）：

mcpServers:
  uptime-kuma:                                                       
    command: npx                                                     
    args: ["-y", "@davidfuchs/mcp-uptime-kuma"]                      
    customUserVars:                                                  
      UPTIME_KUMA_URL:                                               
        title: "Uptime Kuma URL"
        description: "登录Uptime Kuma的URL。"
      UPTIME_KUMA_USERNAME:
        title: "Uptime Kuma Username"
        description: "登录Uptime Kuma的用户名。"
      UPTIME_KUMA_PASSWORD:
        title: "Uptime Kuma Password"
        description: "登录Uptime Kuma的密码。"
    env:
      UPTIME_KUMA_URL: "{{UPTIME_KUMA_URL}}"
      UPTIME_KUMA_USERNAME: "{{UPTIME_KUMA_USERNAME}}"
      UPTIME_KUMA_PASSWORD: "{{UPTIME_KUMA_PASSWORD}}"
    serverInstructions: true
    startup: false

选项2：JWT令牌身份验证（LibreChat）

mcpServers:
  uptime-kuma:
    command: npx
    args: ["-y", "@davidfuchs/mcp-uptime-kuma"]
    customUserVars:
      UPTIME_KUMA_URL:
        title: "Uptime Kuma URL"
        description: "登录Uptime Kuma的URL。"
      UPTIME_KUMA_JWT_TOKEN:
        title: "Uptime Kuma JWT Token"
        description: "用于Uptime Kuma身份验证的JWT令牌。"
    env:                                                             
      UPTIME_KUMA_URL: "{{UPTIME_KUMA_URL}}"
      UPTIME_KUMA_JWT_TOKEN: "{{UPTIME_KUMA_JWT_TOKEN}}"
    serverInstructions: true
    startup: false

请参阅如何找到您的JWT令牌部分以获取说明。

如果您是唯一使用LibreChat服务器的人，您可以移除customUserVars并在env部分直接设置环境变量。您也可以移除startup: false——这仅存在于那里是因为如果没有它，LibreChat会在启动时立即尝试启动mcp-uptime-kuma MCP服务器，但由于用户提供的凭据尚未可用，这会失败。

使用可流式传输的HTTP传输设置mcp-uptime-kuma

推荐使用可流式传输的HTTP运行MCP服务器的方式是作为Docker容器运行。

Github仓库中提供了一个docker-compose.yml文件。下载它并根据您的Uptime Kuma部署更新包含的环境变量，然后运行：

docker compose up -d

MCP端点将在您的Docker主机的3000端口上可用（可通过PORT环境变量进行配置）。如果您更喜欢直接在主机机器上运行，请参阅下面的开发使用部分。

工具详细描述

getMonitorSummary

检索所有监控器的总结列表，包括基本信息及其当前状态。

• 输入：
  • keywords（字符串，可选）：按路径名称过滤监控器的空间分隔关键字（不区分大小写）。所有关键字都必须匹配才能包含监控器。
• 输出：包含以下内容的监控器总结数组：
  • 监控器ID、名称、路径名称
  • 活动和维护状态
  • 最近的心跳状态（0=DOWN，1=UP，2=PENDING，3=MAINTENANCE）
  • 最近心跳的状态消息
  • 不同时间段的正常运行时间百分比（24小时、720小时、1年）
  • 平均ping时间（毫秒）
  • 匹配监控器的总数

getMonitor

根据ID检索特定监控器的详细信息。

• 输入：
  • monitorID（数字）：要检索的监控器ID
  • includeAdditionalFields（布尔值，可选）：是否包含Uptime Kuma的所有附加字段（默认：false）
• 输出：包含如URL、类型、检查间隔、通知设置等详细信息的监控器配置对象。

listMonitors

检索用户有权访问的所有监控器的完整列表。

• 输入：
  • includeAdditionalFields（布尔值，可选）：是否包含Uptime Kuma的所有附加字段（默认：false）
• 输出：包含计数的监控器对象数组。

getHeartbeats

检索特定监控器的心跳（状态检查）。

• 输入：
  • monitorID（数字）：要获取心跳的监控器ID
  • maxHeartbeats（数字，可选）：要返回的最近心跳的最大数量（1-100）。默认：1
• 输出：包含以下内容的对象：
  • monitorID：监控器ID
  • heartbeats：心跳对象数组，包含状态、响应时间、时间戳等
  • count：返回的心跳数量

listHeartbeats

检索所有监控器的心跳。

• 输入：
  • maxHeartbeats（数字，可选）：每个监控器的最近心跳最大数量（1-100）。默认：1
• 输出：包含以下内容的对象：
  • heartbeats：映射到其心跳数组的监控器ID
  • monitorCount：监控器数量
  • totalHeartbeatCount：所有监控器的总心跳数量

getSettings

检索当前Uptime Kuma服务器设置。

• 输入：无
• 输出：包含以下内容的设置对象：
  • serverTimezone：服务器时区设置
  • checkUpdate：是否检查更新
  • searchEngineIndex：搜索引擎索引设置
  • entryPage：入口页面配置
  • dnsCache：DNS缓存设置
  • keepDataPeriodDays：数据保留期限（天）
  • tlsExpiryNotifyDays：TLS过期通知天数
  • trustProxy：信任代理设置
  • nscd：NSCD设置
  • disableAuth：身份验证禁用状态
  • primaryBaseURL：主基础URL（可选）

开发

要在本地运行，克隆仓库并执行以下步骤：

安装依赖项

npm install

创建环境配置

复制.env.example到.env并配置您的Uptime Kuma实例所需的环境变量（URL和身份验证方法）。

构建

将TypeScript代码构建为JavaScript：

npm run build

为了开发时自动重建：

npm run watch

运行

默认（stdio传输）

生产模式运行（需要先构建）：

npm start

或者

npm run start:stdio

此模式设计为由MCP客户端（如Claude Desktop、VS Code等）通过标准输入/输出通信启动。

可流式传输的HTTP传输（用于远程访问）

生产模式运行（需要先构建）：

npm run start:http

默认情况下，HTTP服务器运行在3000端口。您可以通过PORT环境变量更改此端口：

PORT=8080 npm run start:http

MCP端点将在http://localhost:3000/mcp可用。

测试

您可以使用MCP Inspector测试服务器：

npm run inspector

对于HTTP传输：

启动HTTP服务器：

npm run dev:http

然后使用MCP Inspector：

npx @modelcontextprotocol/inspector

连接到：http://localhost:3000/mcp

项目结构

mcp-uptime-kuma/
├── src/
│   ├── index.ts                # 主入口点，选择传输方式
│   ├── server.ts               # 核心MCP服务器配置及工具
│   ├── uptime-kuma-client.ts   # Uptime Kuma API的WebSocket客户端
│   ├── types.ts                # TypeScript类型定义
│   └── version.ts              # 运行时版本信息
├── .github/                    # GitHub工作流程和配置
├── .vscode/                    # VS Code工作区设置
├── docker-compose.yml          # Docker Compose配置
├── Dockerfile                  # Docker镜像定义
├── .dockerignore               # Docker忽略文件
├── .env.example                # 环境配置示例
├── .gitignore                  # Git忽略文件
├── package.json                # 项目依赖和脚本
├── package-lock.json           # 锁定的依赖版本
├── tsconfig.json               # TypeScript配置
├── LICENSE                     # 许可证文件
└── README.md                   # 此文件

开发

要添加新工具或修改现有工具，请编辑src/server.ts。src/uptime-kuma-client.ts中的Uptime Kuma客户端处理WebSocket连接并检索监控器和心跳数据。

更多学习资料

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