Zabbix AI CLI — 面向 AI 代理的 Zabbix MCP 服务器与 CLI

zabbix-ai-cli 是一个集 Zabbix MCP 服务器与命令行客户端于一体的 Go 二进制程序。 它为 Claude Code、Claude Desktop、Codex、Cursor 以及任何其他 Model Context Protocol 客户端提供面向任务的 Zabbix 访问——当前什么出了问题、主机为何静默、告警为何从未到达——输出有界、JSON 契约稳定，并且未经人员批准不会对 Zabbix 做任何更改。

它面向那些会被呼叫的人：运行 Zabbix 的 SRE 和 DevOps 团队，他们希望代理能够对事件进行分类处理，而无需将整个 API 交给它。

需要 Zabbix 6.4 或更高版本。 Bearer-token 认证在 6.4 中引入，并且是唯一实现的方案；更早的版本则期望令牌出现在请求体中。

它从不联系语言模型。AI 做决策，本程序执行，Zabbix 负责监控。

zabbix-ai-cli login
zabbix-ai-cli problems list
zabbix-ai-cli host investigate server01
zabbix-ai-cli alert why 757474
zabbix-ai-cli mcp

为什么不是又一个 Zabbix API 封装

封装 host.get、problem.get 和 history.get 在赋予代理 API 能力的同时，也把 API 的锋利边缘交给了它。在当前的 Zabbix 7.4 服务器上：

• problem.get 没有 selectHosts，因此问题列表到达时不含主机。

• history.get 默认使用 numeric-unsigned 表，对 float 类型的监控项返回空结果——静默地，没有任何错误。

• item.lastvalue 和 item.lastclock 仍然存在，并且已经在多个大版本中返回常量 "0"。

• host.available 在 5.4 中被移除；可用性位于接口上。

• event.acknowledge 接受一个位掩码，而其自身的文档自相矛盾。

• searchWildcardsEnabled: true 禁用了隐式子串匹配，将名称片段变成精确匹配，从而静默地什么都找不到。

上述每一条都会产生一个自信但错误的答案，而不是报错。本工具将这些陷阱吸收到描述任务而非端点的命令背后。

Related MCP server: Zabbix MCP Server

它能做什么

安全性

读操作立即执行。其他操作则不会。

没有任何 MCP 参数可以应用更改，而添加一个也无济于事：代理能发送的确认，提示注入也能发送。批准存在于终端，位于模型的上下文之外。

$ zabbix-ai-cli maintenance create "ms*" --for 2h

PLAN pl_cc89d2e87d15

Create maintenance "ms* (2h0m)" for 2h0m, 2026-08-21T05:39:00Z to 2026-08-21T07:39:00Z

Affects:
  host ms1.8qw.ru
  host ms10.8qw.ru
  ...

Risk: write
Expires: 2026-08-21T05:54:22Z

Nothing has changed yet.
To apply it: zabbix-ai-cli approve pl_cc89d2e87d15

在计划运行之前，其参数会被重新哈希、截止时间会被检查、前置条件会从 Zabbix 重新读取。自计划制定以来已被替换的窗口会被拒绝，而不是被删除。每次应用的更改都会追加到审计日志中。

这比拒绝更重要。当被本工具取代的工具阻止写入时，工作仍然会通过从容器中复制出的令牌完成——丢失了审计轨迹，却什么也没阻止。一条被记录在案的允许路径，胜过一条会被绕过的拒绝。

安装

预构建的归档文件和 ghcr.io 镜像随每个带标签的发布一起发布。在第一个标签落地之前，请使用以下任一方法从源码构建。

要获得主机原生二进制，请使用 Go 1.25 或更高版本：

go install github.com/stufently/zabbix-ai-cli/cmd/zabbix-ai-cli@latest

# Or build the current checkout.
mkdir -p bin
go build -trimpath -o bin/zabbix-ai-cli ./cmd/zabbix-ai-cli

Make 目标以容器优先，不需要主机上安装 Go：

make build      # Linux binary in ./bin, built inside Docker
make docker     # Linux container image for the MCP server

配置

zabbix-ai-cli login --profile prod

它会询问 URL 和 API 令牌，向服务器验证令牌，然后存储它。令牌绝不允许作为标志传入，因为标志值在 shell 历史和进程列表中可见；请改用管道输入：

printf %s "$TOKEN" | zabbix-ai-cli login --profile prod --url https://zabbix.example.com --token-stdin

在配置文件被授予相应作用域之前，写操作处于关闭状态：

zabbix-ai-cli profile scopes prod --add maintenance

有关解析顺序以及无头（headless）和容器场景，请参阅 docs/authentication.md。

将 Zabbix MCP 服务器添加到你的 AI 客户端

MCP 客户端永远不会看到 Zabbix 令牌。它会在服务器进程内部从你配置的配置文件中解析出来，因此凭据永远不会进入模型的上下文或客户端的配置文件中。

Claude Code

claude mcp add zabbix -- zabbix-ai-cli mcp --profile prod
zabbix-ai-cli skills install claude

Claude Desktop

claude_desktop_config.json：

{
  "mcpServers": {
    "zabbix": {
      "command": "zabbix-ai-cli",
      "args": ["mcp", "--profile", "prod"]
    }
  }
}

Codex

# ~/.codex/config.toml
[mcp_servers.zabbix]
command = "zabbix-ai-cli"
args = ["mcp", "--profile", "prod"]

zabbix-ai-cli skills install codex

Cursor、Windsurf、VS Code 及其他 MCP 客户端

任何支持 stdio 的客户端都接受相同的两个字段——命令 zabbix-ai-cli，参数 ["mcp", "--profile", "prod"]。对于希望改用 HTTP 的客户端：

zabbix-ai-cli mcp --http 127.0.0.1:8000

除非你同时传入 --allow-remote 和 bearer 令牌，否则它会拒绝可路由的地址，因为未认证的 MCP 端点就是一条未认证的通往 Zabbix 的路径。请参阅 docs/mcp.md。

Docker

docker run --rm -i \
  -e ZABBIX_AI_CLI_URL=https://zabbix.example.com \
  -e ZABBIX_AI_CLI_TOKEN_FILE=/run/secrets/zabbix \
  -v /path/to/token:/run/secrets/zabbix:ro \
  ghcr.io/stufently/zabbix-ai-cli:latest mcp

MCP 工具

十四个工具，而不是两百个。庞大的工具面在代理做任何事之前就消耗了它的上下文，而且其中大部分永远不会被调用。

zabbix_problems           zabbix_metrics_latest      zabbix_unreachable
zabbix_problem            zabbix_metrics_history     zabbix_maintenance_list
zabbix_hosts              zabbix_alert_why           zabbix_api_call
zabbix_host_status        zabbix_resolve             zabbix_plan_create
zabbix_host_investigate                              zabbix_plan_status

写操作不会各自拥有一个工具。zabbix_plan_create 接受一个 operation 枚举，该枚举由构建 CLI 所用的同一注册表生成，因此工具面不会随着操作的增加而增长。

JSON 契约

{
  "ok": true,
  "data": {},
  "warnings": [],
  "meta": {
    "returned": 50,
    "total": 381,
    "truncated": true,
    "truncated_reason": "row_limit",
    "partial": false,
    "zabbix_version": "7.4.10"
  }
}

错误携带稳定的代码、重试是否值得，以及下一步该做什么：

{
  "ok": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Zabbix rejected the configured API token",
    "retryable": false,
    "suggestion": "run 'zabbix-ai-cli login' to configure a new token"
  }
}

zabbix-ai-cli schema 打印每个操作、其参数及其 JSON Schema，因此代理可以通过编程方式了解工具，而不是猜测标志。

完整细节请参阅 docs/json-output.md。

文档

• 认证与配置文件

• 命令行

• MCP 服务器

• 技能

• JSON 输出与退出码

• 安全模型

• 架构与设计决策

常见问题

什么是 Zabbix MCP 服务器？

MCP 服务器是一个小程序，通过 Model Context Protocol 向 AI 客户端暴露系统。Zabbix MCP 服务器让 Claude、Codex、Cursor 及类似客户端将 Zabbix——问题、主机、监控项、事件、维护——作为工具来查询，而不是让模型猜测针对 JSON-RPC API 的 curl 调用。

AI 代理能通过这个更改我的 Zabbix 吗？

不能自行更改。读操作立即执行。每次写操作都会生成一个计划并停止。应用该计划是人在自己的终端中运行的命令：zabbix-ai-cli approve <plan-id>。没有任何 MCP 参数可以应用任何更改，如果添加了这样的参数，测试会使构建失败。

它会把我的监控数据发送给 AI 提供商吗？

不会。本程序从不联系语言模型。它只与 Zabbix 通信并输出 JSON。你的 MCP 客户端如何处理该输出，是你与你的客户端之间的事。

支持哪些 Zabbix 版本？

Zabbix 6.4 及更高版本，因为 bearer-token 认证在 6.4 中引入。针对 Zabbix 7.4 开发和测试。

我需要安装 Go 吗？

不需要。make build 在 Docker 内部编译，主机上除了 Docker 本身外什么都不需要。go install 用于生成主机原生二进制，每个带标签的发布都会发布带校验和的 Linux、macOS 和 Windows 归档文件，以及 ghcr.io 上的容器镜像。

这与封装 Zabbix API 的 MCP 服务器有何不同？

薄封装把 API 的锋利边缘交给了代理：没有主机的 problem.get、对 float 监控项静默返回空结果的 history.get、冻结在 "0" 的 lastvalue。这些会产生自信的错误答案而不是报错。本工具回答问题——"什么出了问题"、"为什么这个告警没有到达"——并吸收其背后的陷阱。它还提供十四个工具而不是两百个，因为庞大的工具面会在代理做任何工作之前消耗它的上下文。

我还能调用原始的 Zabbix API 吗？

可以，通过 api call，遵循相同的批准规则。分发凭据或执行代码的方法会被直接拒绝——包括迂回的方式，例如创建脚本并让动作运行它。

没有 AI 客户端也能工作吗？

可以。它是一个普通的 CLI，具有人类可读的表格、JSON 输出和文档化的退出码，因此同样可以从 shell 或 CI 任务中使用。

兼容性

Zabbix 6.4 及更高版本。Bearer-token 认证在 6.4 中引入，并且是唯一实现的方案。版本相关行为会被显式断言，因此不兼容会被报告，而不是返回空结果。

针对 Zabbix 7.4 开发和测试。

许可证

Apache-2.0。请参阅 LICENSE。

Zabbix 是 Zabbix LLC 的商标。本项目是一个独立的开源项目，与 Zabbix LLC 无关联，也未获得其认可。