skywalking-zabbix-mcp

简体中文 | English

一个 MCP Server，把 SkyWalking（应用 APM） 和 Zabbix（主机监控） 接进同一个进程，让 AI 助手能在一次对话里既看应用指标、又看机器指标，并把两者关联起来。

它解决什么问题？ 排障时你通常要开两个系统：SkyWalking 看服务慢在哪、Zabbix 看机器是不是扛不住了，然后人脑对时间线判断「是机器先炸拖垮了应用，还是应用自己的 bug」。这个 server 把这一步交给 AI——你问一句「payment-service 怎么了」，它自动拉齐应用侧和机器侧两份数据给出结论。

为什么能自动关联？ SkyWalking 的服务名格式是 <IP>::<服务名>（如 192.0.2.11::payment-service），其中的 IP 段正好就是 Zabbix 里的主机名。两边天然用 IP 对齐，不需要维护任何服务↔主机映射表。

_{真实的 server 代码跑在 mock 后端 上，数据为合成数据。用 uv run python docs/demo/run_demo.py 可自行复现。}

两种运行形态

换句话说：配了 ZABBIX_URL 才会注册 Zabbix 和关联相关的 4 个工具，否则退化为纯 SkyWalking server。

快速上手

1. 安装（三选一）

A. uvx —— 不用 clone，一行跑起来（推荐）

uvx skywalking-zabbix-mcp --version

B. Docker

docker run --rm -i \
  -e SW_URL=http://<oap-host>:12800 \
  ghcr.io/ningjiabing/skywalking-zabbix-mcp

C. 源码（要改代码就用这个）

git clone https://github.com/ningjiabing/skywalking-zabbix-mcp.git
cd skywalking-zabbix-mcp
uv sync
uv run skywalking-zabbix-mcp --version

2. 接入 AI 客户端

claude mcp add obs -s user \
  -e SW_URL=http://<oap-host>:12800 \
  -e ZABBIX_URL=http://<zabbix-host>/zabbix/api_jsonrpc.php \
  -e ZABBIX_USER=<用户> -e ZABBIX_PASSWORD='${MY_ZBX_PWD}' \
  -e READ_ONLY=true \
  -- uvx skywalking-zabbix-mcp

{
  "mcpServers": {
    "obs": {
      "command": "uvx",
      "args": ["skywalking-zabbix-mcp"],
      "env": {
        "SW_URL": "http://<oap-host>:12800",
        "ZABBIX_URL": "http://<zabbix-host>/zabbix/api_jsonrpc.php",
        "ZABBIX_USER": "<用户>",
        "ZABBIX_PASSWORD": "${MY_ZBX_PWD}",
        "READ_ONLY": "true"
      }
    }
  }
}

{
  "mcpServers": {
    "obs": {
      "command": "uvx",
      "args": ["skywalking-zabbix-mcp"],
      "env": {
        "SW_URL": "http://<oap-host>:12800",
        "READ_ONLY": "true"
      }
    }
  }
}

[mcp_servers.obs]
command = "uvx"
args = ["skywalking-zabbix-mcp"]

[mcp_servers.obs.env]
SW_URL = "http://<oap-host>:12800"
ZABBIX_URL = "http://<zabbix-host>/zabbix/api_jsonrpc.php"
ZABBIX_USER = "<用户>"
READ_ONLY = "true"

codex mcp add obs -- uvx skywalking-zabbix-mcp

{
  "servers": {
    "obs": {
      "type": "stdio",
      "command": "uvx",
      "args": ["skywalking-zabbix-mcp"],
      "env": {
        "SW_URL": "http://<oap-host>:12800",
        "READ_ONLY": "true"
      }
    }
  }
}

{
  "command": "uv",
  "args": ["--directory", "/绝对路径/skywalking-zabbix-mcp", "run", "skywalking-zabbix-mcp"]
}

凭据一律用 ${ENV} 引用（见配置），别写进命令行或配置文件明文。全部变量见 .env.example。

3. 直接跑（stdio / HTTP）

uvx skywalking-zabbix-mcp                                  # stdio，默认
uvx skywalking-zabbix-mcp sse --port 8000
uvx skywalking-zabbix-mcp streamable --port 8000 --path /mcp

⚠️ sse / streamable 没有任何鉴权，默认只绑 127.0.0.1。绑到其它地址等于把 OAP 和 Zabbix 的读权限（没开 READ_ONLY 时还有写权限）暴露给能连上这个端口的任何人。要对外必须挡一层带认证的反向代理，或在网络层限制。详见 SECURITY.md。

4. 试一句

「诊断一下 192.0.2.11::payment-service」

server 会用 diagnose_service 一次返回该服务的应用指标（cpm / 响应时间 / SLA + 告警）和承载主机的 Zabbix 数据（CPU / 内存 / IO + 当前 problem）。

工具一览

SkyWalking（16 个，任何配置都有）

Zabbix（2 个，配 ZABBIX_URL 才启用）

跨栈关联（2 个，配 ZABBIX_URL 才启用）

另外还有

• 10 个 prompts（排查引导）：analyze-performance compare-services top-services investigate-traces trace-deep-dive analyze-logs explore-service-topology generate_duration build-mqe-query explore-metrics
• 4 个 resources（MQE 文档）：mqe://docs/syntax、mqe://docs/examples、mqe://docs/ai_prompt（静态），mqe://metrics/available（动态，实时列后端指标）

配置

全部通过环境变量。凭据类支持 ${ENV} 展开（如 SW_PASSWORD=${MY_SW_PWD}），避免明文。示例见 .env.example。

ZABBIX_URL 路径别配错：装在子路径的形如 http://host/zabbix/api_jsonrpc.php，装在根路径的形如 http://host:port/api_jsonrpc.php。配错直接 404。

完整 JSON 写法见上面接入 AI 客户端一节。

典型用法

兼容性

新旧 OAP 通吃——启动时自动探测后端版本与 schema 能力，按实际支持裁剪查询：

• 版本探测（version → major.minor）：metadata / endpoints / trace 按版本走 v1 或 v2 查询。
• schema 能力探测（introspection）：alarm / MQE 按后端实际字段裁剪 selection set，避免旧版校验报错。
• MQE 老语法自动改写：service_percentile{p='50,90'} → {_='0,2'}，返回结果再还原成 p 标签。
• coldStage 仅在请求 cold 数据时才下发（旧版 OAP 无此字段）。

Zabbix 4.0 兼容——PHP 污染响应去噪、user 登录参数、body auth 字段、/zabbix/ 子路径，全部自动处理。

安全——SkyWalking 的 16 个工具本就是只读查询；开 READ_ONLY=true 后 Zabbix 侧也只放行 *.get，拦截一切写方法。部署前请读 SECURITY.md：凭据管理、HTTP 传输无鉴权、工具输出会流向 LLM，这三点都要按你的环境评估。

依赖极简——只有 fastmcp + httpx。

开发

uv sync                      # 装运行时 + 开发依赖
uv run pre-commit install    # ruff / 私钥检测 / gitleaks
uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest --cov

测试覆盖 GraphQL 客户端鉴权与错误面、后端版本/能力探测与缓存、trace v1/v2 协议选择与三种视图、MQE 老语法改写、Zabbix 登录/重登/只读守卫/PHP 污染去噪、跨栈关联两个工具的端到端路径，以及「纯 SkyWalking 16 工具、加 Zabbix 变 20 工具」这个契约本身。

贡献流程见 CONTRIBUTING.md。

许可证

Apache License 2.0，见 LICENSE / NOTICE。变更记录见 CHANGELOG.md。SkyWalking 相关查询文本源自 Apache SkyWalking 项目，跨语言移植保留原始许可。