AI导哈

Uptime Kuma MCP 服务器

Uptime Kuma MCP Server 是一个中间件服务器，用于与 Uptime Kuma 实例交互，提供管理监控器、标签、状态页面和检索心跳数据的功能。

  • by phukit29182
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 phukit29182/uptime-kuma-mcp-server

使用说明

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. 正常运行时间Kuma API集成： 调用每个工具时，首先尝试使用 uptime-kuma-api Python客户端库。
  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服务器。要在此模式下运行，您需要修改 if __name__ == "__main__": 把…的车堵住 main.py 呼叫 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}).有关可用字段，请参阅正常运行时间Kuma API。
  • 退货： 指示成功或失败的字典，以及API响应。

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

  • 说明： 向特定监视器添加标签。
  • 参数：
    • monitor_id （整数）：监视器的ID。
    • tag_id （整数）：要添加的标签的ID。
    • value （string）：标记的值。
  • 退货： 指示成功或失败的字典，以及API响应。

delete_monitor_tag(monitor_id: int, tag_id: int)

  • 说明： 从特定监视器中删除标记。
  • 参数：
    • monitor_id （整数）：监视器的ID。
    • tag_id （整数）：要删除的标记的ID。
  • 退货： 指示成功或失败的字典，以及API响应。

get_status_page(slug: str)

  • 说明： 通过特定状态页的slug检索其详细信息。
  • 参数：
    • slug （string）：状态页面的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级别输出到控制台（标准输出），包括时间戳、记录器名称、日志级别和消息。

错误处理

  • 配置错误： 服务器将无法启动（引发 ValueError)如果关键的正常运行时间Kuma环境变量(KUMA_URL, KUMA_USERNAME, KUMA_PASSWORD)未设置。
  • API错误： 记录与正常运行时间Kuma API交互期间的错误（例如，登录失败、监视器ID无效）。这些工具通常会返回一个字典，其中包含一个“状态”字段，指示“错误”或“失败”，以及一个“错误消息”。
  • 一般例外情况： 工具处理程序中未捕获的异常会被记录并重新引发，使FastMCP框架能够适当地处理它们（这可能涉及向客户端发送错误响应）。

相关 MCP