Uptime Kuma MCP Server

Uptime Kuma MCP 服务

本项目提供一个 FastMCP（消息控制协议）服务，作为中间层与 Uptime Kuma 实例交互。它提供一组工具，用于管理监控项、标签、状态页，以及从 Uptime Kuma 获取心跳数据。

功能

服务提供以下工具：

• 登录 Uptime Kuma：（内部函数，供所有工具使用）
• add_monitors：向 Uptime Kuma 添加多个 HTTP 监控项。
• get_monitors：获取所有监控项的列表。
• delete_monitors：根据 ID 删除指定的监控项。
• pause_monitor：暂停指定的监控项。
• resume_monitor：恢复指定的监控项。
• get_monitor_beats：获取指定监控项的心跳数据。
• edit_monitor：编辑现有监控项的属性。
• add_monitor_tag：为指定监控项添加标签。
• delete_monitor_tag：删除指定监控项的标签。
• get_status_page：获取指定状态页的详细信息。
• get_heartbeats：在指定时间范围内获取指定监控项的心跳数据，并支持分页。
• get_tags：获取 Uptime Kuma 中定义的所有标签。

工作原理

1. FastMCP 服务： 应用的核心是一个 FastMCP 服务实例。此服务会监听传入的请求，以执行预定义的“工具”。
2. Uptime Kuma API 集成： 每个工具在调用时，都会首先尝试使用 uptime-kuma-api Python 客户端库登录配置的 Uptime Kuma 实例。
3. 异步操作： 服务使用 asyncio 构建，以实现非阻塞 I/O。由于 uptime-kuma-api 库是同步的，因此会将其调用封装在 loop.run_in_executor 中，以防止阻塞服务的事件循环。
4. 环境配置： Uptime Kuma 凭据和服务绑定信息等关键配置详情通过环境变量管理，并从 .env 文件加载。
5. 工具定义： 每项对外提供的功能（例如 add_monitors、get_monitors）都定义为使用 @mcp.tool() 装饰的异步函数。这些工具负责处理与 Uptime Kuma API 交互的逻辑并格式化响应。

前置条件

• Python 3.7+（因为使用了 asyncio.get_running_loop()）
• 一个 Uptime Kuma 实例。
• Uptime Kuma 实例的访问凭据（用户名、密码）。

设置

1. 克隆仓库（如适用）：

   git clone <repository_url>
   cd uptime-kuma-mcp-server
   

2. 安装依赖项： 建议使用虚拟环境。

   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   

运行服务

服务可以通过两种模式运行：

1. STDIO 模式（默认）： 此模式使用标准输入/输出进行通信，通常用于由其他应用程序将服务作为子进程管理的场景。

   python main.py
   

   服务将启动，并在控制台记录运行情况。

2. SSE（服务器发送事件）模式： 此模式会运行一个使用服务器发送事件进行通信的 HTTP 服务。若要使用此模式，需要修改 main.py 中的 if __name__ == "__main__": 代码块，改为调用 main_sse() 而非 main_stdio()。

   main.py 中的修改示例：

   if __name__ == "__main__":
       # logger.info("Starting MCP server in STDIO mode as per __main__ block...")
       # main_stdio()
       # logger.info("MCP server (stdio mode) has finished or exited.")
   
       logger.info("Starting MCP server in SSE mode...")
       main_sse() # Call main_sse() here
       logger.info("MCP server (SSE mode) has finished or exited.")
   

   然后运行：

   python main.py
   

   服务将在环境变量 MCP_HOST 和 MCP_PORT 指定的主机和端口上监听（默认值为 0.0.0.0:8000）。

工具详情

所有工具都会先尝试登录 Uptime Kuma。若登录失败，工具执行将失败。

add_monitors(urls: list[str])

• **说明：**向 Uptime Kuma 添加多个 HTTP 监控项。
• 参数：
  • urls（字符串列表）：要为其创建监控项的 URL 列表。监控项名称根据 URL 生成。
• **返回：**包含 monitor_addition_results、kuma_url、total_requested 和 successfully_added 的字典。

get_monitors()

• **说明：**获取 Uptime Kuma 中所有监控项的列表。
• **参数：**无。
• **返回：**包含 monitors（精简后的列表）、total_count 和 kuma_url 的字典。

delete_monitors(ids: list[int])

• **说明：**根据 ID 删除指定的监控项。
• 参数：
  • ids（整数列表）：要删除的监控项 ID 列表。
• **返回：**包含 monitor_deletion_results、total_requested、successfully_deleted 和 kuma_url 的字典。

pause_monitor(monitor_id: int)

• **说明：**暂停指定的监控项。
• 参数：
  • monitor_id（整数）：要暂停的监控项 ID。
• **返回：**指示成功或失败并包含 API 响应的字典。

resume_monitor(monitor_id: int)

• **说明：**恢复指定的监控项。
• 参数：
  • monitor_id（整数）：要恢复的监控项 ID。
• **返回：**指示成功或失败并包含 API 响应的字典。

get_monitor_beats(monitor_id: int, hours: int = 1)

• **说明：**获取指定监控项在给定时间范围内的心跳记录。
• 参数：
  • monitor_id（整数）：监控项的 ID。
  • hours（整数，默认值：1）：要获取的心跳记录时间范围，即距当前时间的小时数。
• **返回：**包含 beats、count 和 status 的字典。

edit_monitor(monitor_id: int, options: dict)

• **说明：**编辑现有监控项。
• 参数：
  • monitor_id（整数）：要编辑的监控项 ID。
  • options（字典）：要更新的监控项属性（例如，{"name": "New Name", "interval": 60}）。可用字段请参阅 Uptime Kuma API。
• **返回：**指示成功或失败并包含 API 响应的字典。

add_monitor_tag(monitor_id: int, tag_id: int, value: str)

• **说明：**为指定监控项添加标签。
• 参数：
  • monitor_id（整数）：监控项的 ID。
  • tag_id（整数）：要添加的标签 ID。
  • value（字符串）：标签的值。
• **返回：**指示成功或失败并包含 API 响应的字典。

delete_monitor_tag(monitor_id: int, tag_id: int)

• **说明：**从指定监控项中删除标签。
• 参数：
  • monitor_id（整数）：监控项的 ID。
  • tag_id（整数）：要删除的标签 ID。
• **返回：**指示成功或失败并包含 API 响应的字典。

get_status_page(slug: str)

• **说明：**根据 slug 获取指定状态页的详情。
• 参数：
  • slug（字符串）：状态页的 slug。
• **返回：**包含状态页 data 或错误消息的字典。

get_heartbeats(offset: int = 0, limit: int = 100)

• **说明：**分页获取心跳监控数据。
  • 注意：此工具会先从 Uptime Kuma 获取所有心跳记录，然后在服务端进行分页。对于非常大的数据集，这可能效率低下。
• 参数：
  • offset（整数，默认值：0）：分页偏移量。
  • limit（整数，默认值：100）：每页心跳记录数量上限。
• **返回：**包含分页后的 data、total_available、count_returned、offset 和 limit 的字典。

get_tags()

• 描述： 获取 Uptime Kuma 中定义的所有标签。
• 参数： 无。
• 返回： 一个字典，其中包含标签列表（data）及其数量（count）。

日志记录

该服务使用 Python 的 logging 模块。默认情况下，日志以 INFO 级别输出到控制台（标准输出），并包含时间戳、日志记录器名称、日志级别和消息。

错误处理

• 配置错误： 如果未设置 Uptime Kuma 的必要环境变量（KUMA_URL、KUMA_USERNAME、KUMA_PASSWORD），服务将无法启动（并引发 ValueError）。
• API 错误： 与 Uptime Kuma API 交互期间发生的错误（例如登录失败、监控器 ID 无效）会被记录。工具通常会返回一个包含 "status" 字段（值为 "error" 或 "failed"）和 "error_message" 的字典。
• 一般异常： 工具处理程序中未捕获的异常会被记录并重新引发，以便 FastMCP 框架妥善处理（这可能包括向客户端发送错误响应）。