Zabbix AI CLI

Zabbix AI CLI MCP — 面向 AI Agent 的 Zabbix MCP 服务和 CLI

zabbix-ai-cli-mcp 是一个 Go 二进制程序，集成了 Zabbix MCP 服务和命令行客户端。 它为 Claude Code、Claude Desktop、Codex、Cursor 及其他 Model Context Protocol 客户端提供面向任务的 Zabbix 访问能力——现在出了什么问题、主机为何没有响应、告警为何迟迟未送达——同时提供有界输出和稳定的 JSON 契约，并通过一个设置 allow_write 决定由 Agent 应用更改，还是由人来审批计划。

它面向需要随时响应告警的人员：运行 Zabbix、希望 Agent 能够分诊事件，又不想把整个 API 交给 Agent 的 SRE 和 DevOps 团队。

需要 Zabbix 6.4 或更高版本。 Bearer 令牌身份验证从 6.4 开始提供；这是本程序唯一实现的身份验证方式。更早的版本要求将令牌放在请求正文中。

它不会联系任何大模型。AI 负责决策，本程序负责执行，Zabbix 负责监控。

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

为什么不再做一个 Zabbix API 封装

封装 host.get、problem.get 和 history.get，会把 API 的棘手之处连同它的功能一起交给 Agent。在当前的 Zabbix 7.4 服务上：

• problem.get 没有 selectHosts，因此问题列表中不会包含主机。
• history.get 默认使用无符号数值表；对于浮点型监控项，它会什么也不返回——悄无声息，也没有错误。
• item.lastvalue 和 item.lastclock 仍然存在，而且在多个主要版本中一直返回常量 "0"。
• host.available 已在 5.4 中移除；可用性信息现在位于接口上。
• event.acknowledge 使用位掩码，而它自己的文档对此还有自相矛盾之处。
• searchWildcardsEnabled: true 会禁用隐式子串匹配，使名称片段变成精确匹配，且悄然找不到任何结果。

这些情况都会给出自信却错误的答案，而不是报错。本工具将它们封装在描述任务而非 API 端点的命令之后。

功能

命令	可回答的问题
problems list	现在出了什么问题——包括被抑制的问题，并注明隐藏这些问题的维护窗口
host investigate	一次调用即可获取：主机状态、活动问题、近期事件、无响应和不受支持的监控项，以及维护信息
host status	仅返回少量字段，而非多达一万两千个字符的配置信息
alert why	通知为何送达或未送达——抑制情况、投递尝试、动作、媒介类型，以及每位接收者的严重性筛选器
resolve	将从聊天中粘贴的通知转换为事件、主机和触发器标识符
unreachable	列出 Zabbix 无法轮询的受监控主机及其记录的错误
metrics latest / history	返回采用正确历史类型、人类可读单位以及 min/avg/max 的值
maintenance	创建、延长、结束或移除维护窗口，支持 ms* 这样的主机模式
mediatypes enable / disable	仅更改媒介类型的状态，即可恢复或停止告警投递
discoveryrules set-lost-resources	调整丢失的 LLD 资源的禁用／删除策略，并提供影响计划
api call	在相同规则下使用的应急通道

安全性

读取操作始终会立即执行。其他操作是否执行，取决于一个设置：allow_write，默认开启。

# ~/.config/zabbix-ai-cli-mcp/config.toml
allow_write = true            # the default; omit the key and you get this

[profiles.prod]
url = "https://zabbix.example.com"
allow_write = false           # this one profile is an exception

如果不确定，请设置 allow_write = false。 这样每次更改需要多执行一条命令；对于不能承受 Agent 意外操作的安装环境，这是正确的默认设置。配置文件中的设置会被配置文件级别的覆盖项覆盖，而 ZABBIX_AI_CLI_MCP_ALLOW_WRITE 的优先级高于这两者——这样就能在不持有配置文件的情况下告知容器该设置。

调用方	allow_write = true	allow_write = false
CLI，终端前的用户	--apply 会应用更改	先生成计划，再 approve
MCP，Agent	zabbix_write 会应用更改	先生成计划，再在终端运行 approve

关闭写入后，不会有任何工具或标志应用更改：系统会描述更改内容，用户则在自己的终端运行 zabbix-ai-cli-mcp approve <plan-id>。Agent 能发送的确认也可能是提示词注入攻击发送的确认，因此不提供这种方式——审批在模型上下文之外进行。

开启写入后，Agent 会自行应用更改，每项更改都会记录在审计日志中，包括配置文件、参数、涉及的对象，以及发起请求的是用户还是模型。无论此设置如何，zabbix-ai-cli-mcp mcp --read-only 都会拒绝这两种路径；而可以写入的 HTTP 端点若没有 Bearer 令牌，则会拒绝启动。

无论开启还是关闭写入，其他限制始终有效：配置文件中的 scopes 仍会限定可操作的范围，风险注册表仍会拒绝那些会泄露凭据或运行代码的方法，并且计划在执行前仍会根据实时 Zabbix 数据重新检查。

$ zabbix-ai-cli-mcp 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-mcp approve pl_cc89d2e87d15

媒体渠道状态和丢失的 LLD 资源策略也使用这套审批／审计流程。媒体状态请求支持幂等操作，可供外部 cron 使用；LLD 计划会显示主机范围和丢失项目数量，并将历史记录删除标记为破坏性操作。请参阅参数和示例。

计划运行前，系统会重新计算其参数哈希、检查截止时间，并从 Zabbix 重新读取前置条件。如果计划生成后某个时间窗口已被替换，系统会拒绝操作，而不会删除它。每项已应用的更改都会追加到审计日志中。

这一点比拒绝操作本身更重要。当它替代的工具阻止写入时，人们仍会从容器中复制令牌来完成工作——既没有阻止任何操作，又丢失了审计记录。经过记录的许可操作，胜过会被绕过的拒绝。

安装

在 Linux 或 macOS 上，将以下内容粘贴到终端。它会获取最新版本，根据 checksums.txt 校验文件，将二进制文件放入 ~/.local/bin，并通过标准输入／输出启动 MCP 服务。请先替换两个占位符：

VERSION=$(curl -fsSLI -o /dev/null -w '%{url_effective}' \
  https://github.com/stufently/zabbix-ai-cli-mcp/releases/latest | sed 's|.*/v||')
OS=$(uname -s | tr '[:upper:]' '[:lower:]')                      # linux | darwin
ARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')        # amd64 | arm64
ARCHIVE=zabbix-ai-cli-mcp_${VERSION}_${OS}_${ARCH}.tar.gz
BASE=https://github.com/stufently/zabbix-ai-cli-mcp/releases/download/v${VERSION}

TMP=$(mktemp -d) && cd "$TMP"
curl -fsSLO "$BASE/$ARCHIVE" && curl -fsSLO "$BASE/checksums.txt"
grep " $ARCHIVE\$" checksums.txt | shasum -a 256 -c -   # sha256sum -c - works too
tar -xzf "$ARCHIVE"
mkdir -p ~/.local/bin && install -m 0755 zabbix-ai-cli-mcp ~/.local/bin/
~/.local/bin/zabbix-ai-cli-mcp --version
ZABBIX_AI_CLI_MCP_URL=https://zabbix.example.com ZABBIX_AI_CLI_MCP_TOKEN=your-api-token ~/.local/bin/zabbix-ai-cli-mcp mcp

最后一行是下面每个客户端配置块都会运行的命令：zabbix-ai-cli-mcp，参数为 ["mcp"]，Zabbix URL 和 API 令牌则从环境变量中读取。启动后按 Ctrl-C 停止；之后由客户端启动该程序。~/.local/bin 必须位于 PATH 中，因为客户端配置会按名称调用该二进制文件；否则，请提供其绝对路径。

预编译二进制文件（无需 Go）

每个带标签的版本都会发布适用于 amd64 和 arm64 的 Linux、macOS 及 Windows 压缩包，以及 checksums.txt。本节顶部的代码块会在 Linux 或 macOS 上安装其中一个版本。压缩包中还包含 docs/ 和 Agent 技能。

在 Windows（PowerShell）上，压缩包为 zip 文件：

$Version = (Invoke-RestMethod https://api.github.com/repos/stufently/zabbix-ai-cli-mcp/releases/latest).tag_name.TrimStart('v')
$Arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'amd64' }
$Zip = "zabbix-ai-cli-mcp_${Version}_windows_${Arch}.zip"
$Base = "https://github.com/stufently/zabbix-ai-cli-mcp/releases/download/v$Version"
Invoke-WebRequest "$Base/$Zip" -OutFile $Zip
Invoke-WebRequest "$Base/checksums.txt" -OutFile checksums.txt
$Want = ((Select-String -Path checksums.txt -Pattern " $Zip$").Line -split '\s+')[0]
if ((Get-FileHash $Zip -Algorithm SHA256).Hash -ne $Want) { throw "checksum mismatch" }
Expand-Archive $Zip -DestinationPath "$env:LOCALAPPDATA\zabbix-ai-cli-mcp" -Force
& "$env:LOCALAPPDATA\zabbix-ai-cli-mcp\zabbix-ai-cli-mcp.exe" --version

将 %LOCALAPPDATA%\zabbix-ai-cli-mcp 添加到 PATH，或者在客户端配置中使用 zabbix-ai-cli-mcp.exe 的完整路径。

从源码构建

若要构建适用于当前主机的版本，请使用 Go 1.25 或更高版本：

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

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

Make 目标以容器为先，无需在主机上安装 Go：

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

检查版本的来源

checksums.txt 可以证明下载文件完整，但无法证明由谁构建：有权替换压缩包的人，也能替换它旁边的校验和文件。从添加本节后首次发布的版本开始，发布工作流还会为每个压缩包、每个 .mcpb 捆绑包和容器映像签署构建来源证明（通过 GitHub artifact attestations 使用 Sigstore）。使用 GitHub CLI：

verify() {
  gh attestation verify "$1" --repo stufently/zabbix-ai-cli-mcp \
    --source-ref "refs/tags/v$VERSION" \
    --signer-workflow stufently/zabbix-ai-cli-mcp/.github/workflows/release.yml \
    --deny-self-hosted-runners
}
verify "$ARCHIVE"
verify "zabbix-ai-cli-mcp-${VERSION}-linux-amd64.mcpb"
verify "oci://ghcr.io/stufently/zabbix-ai-cli-mcp:$VERSION"

验证通过表示该文件由此仓库的发布工作流在 GitHub 托管的运行器上从标签 v$VERSION 构建：来自其他版本发布的已证明文件，即使只是改了名称，也无法通过 --source-ref 验证。包括 0.4.3 在内的早期版本仅附带校验和。

配置

zabbix-ai-cli-mcp login --profile prod

系统会询问 URL 和 API 令牌，验证令牌是否与服务匹配，然后将其保存。不会接受作为标志传入的令牌，因为标志值会显示在 shell 历史记录和进程列表中；请通过管道传入：

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

未指定任何范围的配置文件可以执行写入设置允许的任何操作。指定任何范围后，权限就会严格限制为这些范围：

zabbix-ai-cli-mcp profile scopes prod --add maintenance
zabbix-ai-cli-mcp profile show prod        # what it may do, writes included

请参阅 docs/authentication.md，了解解析顺序，以及无头和容器环境下的情况。

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

以下每个代码块都会使用参数 ["mcp"] 运行 zabbix-ai-cli-mcp，与上面的安装命令相同。env 中的 URL 和 API 令牌是占位符：请替换它们，且不要提交真实令牌。如果希望不将令牌保存在客户端中，请运行 zabbix-ai-cli-mcp login，并在 args 中传入 --profile 和配置文件名称，代替这两个变量。

Claude Code

项目根目录下的项目文件 .mcp.json：

{
  "mcpServers": {
    "zabbix": {
      "command": "zabbix-ai-cli-mcp",
      "args": ["mcp"],
      "env": {
        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",
        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"
      }
    }
  }
}

也可以在终端中注册同一服务。在启动 Claude Code 的环境中设置这两个变量，或者使用上面的 .mcp.json：

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

Claude Desktop

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/claude_desktop_config.json、Windows %APPDATA%\Claude\claude_desktop_config.json、Linux ~/.config/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "zabbix": {
      "command": "zabbix-ai-cli-mcp",
      "args": ["mcp"],
      "env": {
        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",
        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"
      }
    }
  }
}

Claude Desktop 也支持一键安装此服务。从 https://github.com/stufently/zabbix-ai-cli-mcp/releases/latest 下载适用于你操作系统的 .mcpb 并打开。Desktop 会询问 Zabbix URL、API 令牌，以及是否允许写入操作（Desktop 扩展默认关闭）。请参阅 docs/mcp.md。

同一版本还会发布 checksums.txt，其中包含每个 .mcpb 的 SHA256。请将该文件下载到与捆绑包相同的目录中，并在打开捆绑包前进行校验：

sha256sum -c --ignore-missing checksums.txt   # run next to the downloaded .mcpb

在 macOS 上，筛选出捆绑包对应的行，并使用 shasum -a 256 -c - 进行校验。

Cursor

该按钮会从你的 PATH 运行 zabbix-ai-cli-mcp（参见安装）；安装后，请在 ~/.cursor/mcp.json 中将占位符替换为你的 URL 和令牌。也可以手动添加下面的代码块。

~/.cursor/mcp.json，或项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "zabbix": {
      "command": "zabbix-ai-cli-mcp",
      "args": ["mcp"],
      "env": {
        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",
        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"
      }
    }
  }
}

Windsurf

mcp_config.json。在 macOS 和 Linux 上，路径为 ~/.config/devin/mcp_config.json （或 $XDG_CONFIG_HOME/devin/mcp_config.json）。在 Windows 上，路径为 %APPDATA%\devin\mcp_config.json。旧版使用 ~/.codeium/windsurf/mcp_config.json。

{
  "mcpServers": {
    "zabbix": {
      "command": "zabbix-ai-cli-mcp",
      "args": ["mcp"],
      "env": {
        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",
        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"
      }
    }
  }
}

Zed

Zed 将 MCP 服务称为上下文服务。配置文件为 settings.json （zed: open settings file）：

{
  "context_servers": {
    "zabbix": {
      "command": "zabbix-ai-cli-mcp",
      "args": ["mcp"],
      "env": {
        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",
        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"
      }
    }
  }
}

也可以通过 Settings → AI → MCP Servers → Add Server → Add Local Server 添加相同配置；服务器名称旁的指示器会显示服务器是否已启动。

Codex

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

zabbix-ai-cli-mcp skills install codex

VS Code

其他任何 stdio 客户端都使用相同的命令 zabbix-ai-cli-mcp 和参数 ["mcp"]，并通过环境变量传入 URL 和令牌。对于需要使用 HTTP 的客户端：

zabbix-ai-cli-mcp mcp --http 127.0.0.1:8000 --bearer-token "$MCP_TOKEN"

可写入的服务若未提供 bearer token，则拒绝通过 HTTP 启动，即使地址是回环地址也不例外：没有令牌时，机器上的任何进程都可以通过它更改 Zabbix。若要绑定到可路由地址，必须同时传入 --allow-remote 和 bearer token，否则未经过身份验证的 MCP 端点就成了通往 Zabbix 的未验证入口。请参阅 docs/mcp.md。

Docker

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

MCP 工具

共 15 个工具，而不是 200 个。庞大的工具集会在 Agent 尚未执行任何操作之前就消耗上下文，而且其中大多数工具永远不会被调用。

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_write

写入操作不会各自对应一个工具。zabbix_write 和 zabbix_plan_create 接受一个 operation 枚举，该枚举由构建 CLI 时使用的同一注册表生成，因此添加操作不会扩大工具集。只有在 allow_write 允许的情况下，才会提供 zabbix_write。

提示词示例

• 为什么 web01 的磁盘告警一直没有送达？
• Zabbix 目前有哪些故障？
• Zabbix 一直无法轮询哪些受监控主机？
• 过去一天 db01 的 CPU 状况如何？

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-mcp login' to configure a new token"
  }
}

zabbix-ai-cli-mcp schema 会输出每项操作、其参数和 JSON Schema，让 Agent 能以编程方式了解工具，而不必猜测标志参数。

详细信息请参阅 docs/json-output.md。

文档

• 身份验证和配置文件
• 命令行
• MCP 服务
• 技能
• JSON 输出和退出代码
• 安全模型
• 架构和设计决策

常见问题

什么是 Zabbix MCP 服务？

MCP 服务是一种小型程序，可通过 Model Context Protocol 向 AI 客户端开放系统。Zabbix MCP 服务让 Claude、Codex、Cursor 等类似客户端能够将问题、主机、监控项、事件、维护等作为工具查询 Zabbix，而不是让模型对着 JSON-RPC API 猜测 curl 调用。

AI Agent 能通过它更改我的 Zabbix 吗？

这由你决定，相关设置是 allow_write。默认情况下该设置为开启状态，Agent 可以自行开启维护时段或确认事件——每项更改都会经过审计，并受到配置文件作用域和风险注册表的约束。

将 allow_write = false 设为关闭写入权限后，它就无法进行更改。此时，写入操作会生成计划并停止；应用计划需要你在自己的终端中运行命令 zabbix-ai-cli-mcp 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 的棘手之处直接交给 Agent：不指定主机的 problem.get、对浮点型监控项静默返回空结果的 history.get，以及冻结为 "0" 的 lastvalue。这些问题不会报错，反而会让 Agent 给出信心十足的错误答案。这个工具直接回答“哪里出了问题”“为什么没有收到这条告警”等问题，并处理背后的陷阱。它还只提供 15 个工具，而不是 200 个，因为庞大的工具集合会在 Agent 开始工作之前就耗尽其上下文。

我还可以调用原始 Zabbix API 吗？

可以，通过 api call 调用，且遵循与其他功能相同的规则。凡是会泄露凭据或执行代码的方法，都会被直接拒绝——包括绕远路的做法，例如创建脚本，再让某个动作运行它。

没有 AI 客户端也能使用吗？

可以。它是一个常规 CLI，提供易读的表格、JSON 输出和有文档说明的退出代码，因此同样适用于 Shell 或 CI 任务。

已测试的客户端和平台

这里只列出实际运行过的项目。上文针对 Claude Desktop、 Cursor、Windsurf、Zed 和 VS Code 的客户端配置，遵循各客户端文档中说明的 MCP 配置，维护者尚未实际测试；欢迎反馈。

客户端	操作系统	服务运行方式	验证情况
Claude Code 2.1	Ubuntu 26.04，x86_64	通过 stdio 使用 ghcr.io/stufently/zabbix-ai-cli-mcp 镜像（docker run -i）	自 0.1.0 起日常用于 Zabbix 7.4.10；于 2026-10-12 重新检查 tools/list
Codex CLI 0.162	Ubuntu 26.04，x86_64	使用 make build 构建二进制文件，通过 stdio 运行	自 0.3.0 起日常用于同一 Zabbix；于 2026-10-12 重新检查 tools/list
无（CI）	Ubuntu（GitHub 托管），x86_64	单元测试和竞态测试、容器镜像启动	每个拉取请求
无（CI）	macOS amd64 和 arm64、Windows amd64、Linux arm64	仅交叉编译，从未执行	每个拉取请求

兼容性

支持 Zabbix 6.4 及更高版本。Bearer-token 身份验证从 6.4 开始提供，也是本项目唯一实现的身份验证方式。对于依赖版本的行为，项目会进行明确断言，因此遇到不兼容情况时会报告错误，而不是返回空结果。

基于 Zabbix 7.4 开发并测试。

许可证

Apache-2.0。请参阅 LICENSE。

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