prtg-mcp

用于 PRTG Network Monitor（Paessler 网络/基础设施监控）的 MCP 服务器。将 PRTG 原生 HTTP API 的传感器、设备及历史传感器数据暴露为 MCP 工具。

概述

• 无状态 HTTP 服务。任何凭据都不会被持久化——每次请求通过请求头提供自己的凭据，仅在该次请求的生命周期内使用。

• 支持并发请求；每次请求的凭据隔离通过 Python contextvars 实现，而非全局/共享客户端实例。

• 入口点：POST /mcp（MCP 协议）和 GET /health（健康检查）。

• 默认端口：8080（可通过 MCP_HTTP_PORT 配置）。

Related MCP server: mcp-ntopng

认证

与本项目中的大多数集成不同，PRTG 没有单独的登录或令牌交换：用户名和"passhash"（在 PRTG UI 的 My Account -> API Key 下生成，不是账号明文密码）在每次调用中作为明文查询参数发送。因此无需缓存任何内容——每次调用本身已完全自包含且无状态，这正是厂商的设计。

HEADER 授权参数说明

缺少任一 header 返回 401：

{
  "error": "Missing credentials",
  "message": "This server requires the X-PRTG-Server-Url, X-PRTG-Username, and X-PRTG-Passhash headers",
  "required_headers": ["X-PRTG-Server-Url", "X-PRTG-Username", "X-PRTG-Passhash"],
  "optional_headers": []
}

无效凭据会以工具级错误信封（见下文 错误信封）的形式呈现，根据 PRTG 的 HTTP 状态码分类——401/403 映射为 unauthorized。对于任何非 2xx 响应，本服务器会尝试从 JSON 主体中提取 message/error 字段；如果主体不是 JSON，则回退到原始响应文本（PRTG 对于某些格式错误的请求，即使在 .json 端点上也可能回退到 XML <error> 主体）。

环境变量

MCP 端点

• POST /mcp — MCP 协议（可流式 HTTP 传输）

• GET /health — 健康检查，返回 {"status": "ok"}（纯本地探测，不调用 PRTG）

工具列表

所有 3 个工具均为只读（readOnlyHint=True、idempotentHint=True）；本服务不提供任何写入/删除工具。

count 在 PRTG 的 table.json 端点上没有厂商文档化的硬上限，因此本服务器采用平台自身的回退上限，而不是不加检查地透传值：默认 50，超过 200 的值会被静默截断为 200，而不是原样发送给 PRTG。

响应格式

本服务器调用的两个端点（table.json、historicdata.json）都是厂商的 JSON 后缀变体，因此成功时客户端只需解析 JSON。PRTG 的 HTTP API 原则上可能对其他端点/参数返回 XML，因此客户端采用防御式解析：非 2xx 响应被归类到下面的结构化错误信封中；如果 2xx 响应无法解析为 JSON，其原始文本会在 raw_response 键下返回，而不是抛出异常。

错误信封

工具错误以结构化 JSON 字符串的形式返回，而不是抛出异常，这样调用代理可以根据 code 进行分支，决定是否重试：

{"error": {"code": "upstream_error", "message": "...", "retryable": true}}

code 取值为：not_configured、unauthorized、not_found、invalid_argument、rate_limited、upstream_error。空结果集作为正常（非错误）的空集合返回，而不是 not_found。

工具返回值（成功和错误均如此）为紧凑 JSON（ensure_ascii=False，无 indent），上限为 20,000 字符——超大的结果会截断其最大的列表字段，并报告 truncated/original_count，而不是返回无界的数据块。

测试示例

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-PRTG-Server-Url: prtg.example.com" \
  -H "X-PRTG-Username: api_user" \
  -H "X-PRTG-Passhash: <your-passhash>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "prtg_get_sensors",
      "arguments": {}
    }
  }'

实机验证（2026-07-30）：针对真实的 PRTG core server，所有 3 个工具通过本运行中的服务器使用真实凭据端到端调用：prtg_get_sensors 和 prtg_get_devices 均返回 200，带有真实的 prtg-version 字符串和有效的（空）结果集——该测试账号恰好没有配置任何传感器/设备在其可见范围内，但通过使用完全相同的凭据单独查询 content=probes（返回了真实数据，即 PRTG Root probe 以及多个真实调度对象），确认这是真实的"无数据"状态（而非认证失败）。prtg_get_sensor_historic_data 使用非传感器对象 ID 调用（由于没有真实传感器 ID 可用），正确到达 API 并返回了厂商自身的内容级错误（"所选对象无法在此使用"），证明请求/认证管道接线正确。

API 参考

• 公开，无需登录：

  • 传感器/设备表格格式：https://www.paessler.com/manuals/prtg/multiple_object_property_or_status#supported_output

  • 历史数据：https://www.paessler.com/manuals/prtg/historic_data

已知限制

• 范围恰好是 MSPbots 配置的 3 个端点，而非厂商的完整 API 面——PRTG 的 API 还涵盖实时传感器控制（暂停/恢复/确认）、对象创建/删除、通知、报告等；这些不在本范围内。

• 传感器/设备数据无法用真实记录演示——提供的测试账号（Dash_Display，可能是仅用于仪表盘显示的账号）在此特定 PRTG 实例的可见范围内没有配置任何传感器或设备。实机测试通过使用相同凭据成功查询另一个始终有数据的对象类型（content=probes）并返回真实数据，确认这是真实的空结果（而非认证或实现 bug）。

• prtg_get_sensor_historic_data 无法使用真实传感器 ID 测试，原因同上（没有可引用的传感器）；而是通过确认厂商对无效对象 ID 返回的内容级错误响应来验证，这证明请求格式和认证均正确。