Zabbix API MCP

zapi-mcp

英语 | 日语

用于 Zabbix API 的 MCP（Model Context Protocol）服务。

专为网络运维打造：一次 daily_brief 调用即可汇总活动问题，以及特定站点的类别（DHCP 地址池使用率、SNAT 会话使用率、核心网络问题等）；单独的工具则可查询问题、主机和监控项值。组织特定的标签存放在配置文件中，而非代码里，因此该服务保持通用。

自适应版本的身份验证：支持 Zabbix 6.0 LTS（user + auth 字段），并兼容未来的 6.4 / 7.0（username + Authorization: Bearer）。

文档：https://shigechika.github.io/zapi-mcp/

功能

工具	描述
health_check	服务版本、Zabbix 连通性和身份验证、检测到的 API 版本，以及已配置的 daily_brief 类别 — 在会话开始或超时后调用
daily_brief	晨间巡检：活动问题（Warning 及以上）、当前处于维护状态的主机，以及每个已配置类别对应的一个分区
get_problems	按严重性和标签筛选活动问题，按最新优先排序并显示发生时长；标题显示实际总数（达到上限时显示 showing N of TOTAL）；与 Zabbix 前端一样，隐藏禁用的触发器、主机或监控项上的问题（include_disabled=True 可列出这些问题）；输出包含 eventid
get_hosts	按角色／标签／主机组筛选主机列表，并显示 IP 和标签
get_host_items	获取主机当前的监控项值（在服务端按主机筛选）
acknowledge_problem	确认问题并添加消息（不会关闭问题）
set_maintenance	开启幂等的 Zabbix 维护时段，按 location 标签或精确主机名选择主机（两者必须且只能指定其一）
get_maintenance_windows	列出维护时段（活动／即将开始／已过期）— 在将其他工具的告警视为新事件之前进行交叉核查

设置

# uv
uv pip install zapi-mcp

# pip
pip install zapi-mcp

或从源代码安装：

git clone https://github.com/shigechika/zapi-mcp.git
cd zapi-mcp

# uv
uv sync

# pip
pip install -e .

配置

设置以下环境变量：

变量	描述	默认值
ZABBIX_URL	Zabbix 基础 URL（例如 https://zabbix.example.com）；如果 URL 中没有 /api_jsonrpc.php，则会自动追加	必填
ZABBIX_API_TOKEN	Zabbix API 令牌（Zabbix 5.4+），用于替代 ZABBIX_USER／ZABBIX_PASSWORD	两者之一
ZABBIX_USER	Zabbix API 用户	两者之一
ZABBIX_PASSWORD	Zabbix API 密码	两者之一
ZABBIX_CATEGORIES_INI	daily_brief 类别 INI 文件的路径（可选）	—
ZABBIX_BRIEF_RECENT_HOURS	daily_brief 的“近期”时间窗口（小时）；超过此时长的问题会折叠为计数	24
ZABBIX_BRIEF_PROBLEM_LIMIT	每次调用中 daily_brief 获取的活动问题上限；超出部分将计数	1000
ZABBIX_READ_ONLY	设为 true（或 1／yes／on）时，不会注册 acknowledge_problem 和 set_maintenance，因此模型不会看到这些工具。其他任何非 false 值也会被视为只读，并由 health_check 报告	未设置（启用写入工具）

API 用户需要对所查询的主机组拥有读取权限；如果使用 acknowledge_problem，还需拥有确认权限；如果使用 set_maintenance，则需拥有维护写入权限；使用 get_maintenance_windows 和 daily_brief 的“In Maintenance”分区则需维护读取权限（通常默认已包含）。

使用 ZABBIX_API_TOKEN 或 ZABBIX_USER + ZABBIX_PASSWORD 进行身份验证。设置令牌时，遗留的 ZABBIX_USER 会被忽略；如果同时设置令牌、ZABBIX_USER 和 ZABBIX_PASSWORD，则会产生配置错误。令牌无需登录，也无需在客户端配置中保存密码；可以设置过期时间，并可在 Zabbix 的 API 令牌页面单独撤销。

daily_brief 中的活动问题

问题按严重程度分组，并按从新到旧排列，每项都标注其发生时间（例如 3h ago）。超过近期时间窗口（ZABBIX_BRIEF_RECENT_HOURS，默认为 24h）的问题会合并为一行：… and N older (stale; oldest …)。这样一来，Zabbix 因从未自动确认恢复而持续保持活动状态的告警积压（ICMP ping down、RDP down 等），就不会掩盖刚发生的问题。分区标题会显示实际总数；如果获取数量受限，则显示 showing N of TOTAL，绝不会悄悄截断。

daily_brief 中的维护窗口

紧接“活动问题”之后，daily_brief 会列出当前处于活动维护窗口内的主机，以及今天稍后将进入维护窗口的主机，避免其他正在监视这些主机的系统将计划内停机误认为新事件。如果没有内容可显示（没有新情况就没有维护信息），则完全省略 ## In Maintenance 分区。明天或更晚开始的窗口，以及已过期的窗口，不会在此处列出；如需查看完整信息，请调用 get_maintenance_windows（可选传入 include_expired=True）。

daily_brief 的类别（可选）

daily_brief 始终会列出活动问题。要添加特定站点的分区（例如 DHCP 池耗尽、SNAT 会话使用情况、核心网络问题），请将 ZABBIX_CATEGORIES_INI 指向一个 INI 文件。每个 [section] 都是一个类别：

[dhcp]
name = DHCP Pool Usage
# Zabbix host tag identifying the group
tag = dhcp-pool-usage
# report current values for this exact item key
item_key = usage
# flag values >= this
threshold = 80

[snat]
name = SNAT Session Pool
tag = snat-pool-usage
# substring match (catches pool.node0.usage etc.)
item_key_search = .usage
threshold = 80

[core]
name = Core Network
tag = role
# the tag must equal this value
tag_value = main
# no item key -> report active problems instead

• tag（必需）：用于标识类别的主机标签。设置 tag_value 后，标签必须与其相等（Equal）；不设置时，任何带有该标签的主机都会匹配（Exists）。
• item_key / item_key_search：设置其中任一项后，该分区会按值从高到低排序，报告当前的项目值。item_key 会精确匹配键；对于包含 ID 的键，请使用 item_key_search（例如，.usage 可匹配 pool.node0.usage）。如果两者都未设置，则会报告该标签对应的活动问题。
• threshold：可选；达到或超过该值时会标记出来。

请参阅 categories.ini.example。如果未设置该变量或文件不存在，daily_brief 只会报告活动问题。

写入操作

有两个工具会改变状态，其他工具都只读取数据。

工具	Zabbix API 调用
acknowledge_problem	event.acknowledge
set_maintenance	maintenance.create

acknowledge_problem 需要 API 用户拥有确认权限；set_maintenance 需要维护写入权限。缺少任一权限时，服务器对相应工具会保持只读：调用会在 Zabbix API 处失败，而其他工具仍可正常工作。因此，可以将 API 用户交给 AI 助手用于调查，而不授予其更改 Zabbix 配置的权限。只有在工作需要通过助手确认告警或开启维护窗口时，才授予相应权限。

要彻底禁止模型使用写入工具，请设置 ZABBIX_READ_ONLY=true：这两个工具不会被注册，因此客户端看不到它们；即使被调用，它们也会拒绝执行。这样，同一个 Zabbix 用户即可同时服务于只读和启用了写入功能的 MCP 客户端。每个工具还带有 MCP 工具注解（readOnlyHint、destructiveHint、idempotentHint），客户端可据此区分读写工具。

使用方法

Claude Code（插件）

本仓库同时也是一个仅包含单个插件的市场，因此 Claude Code 可以为你安装该服务：

/plugin marketplace add shigechika/zapi-mcp
/plugin install zapi-mcp@zapi-mcp

该插件会启动 uvx zapi-mcp，并读取配置中所述的相同环境变量；请在启动 Claude Code 之前导出这些变量。ZABBIX_CATEGORIES_INI 可以不设置。

运行 Claude Code 的进程必须能在 PATH 中找到 uvx。登录 shell 通常已包含它，但通过 GUI 启动的应用可能没有；如果插件无法启动，请在系统范围内安装 uv。

Claude Code（手动配置）

添加到 .mcp.json：

{
  "mcpServers": {
    "zapi-mcp": {
      "type": "stdio",
      "command": "zapi-mcp",
      "env": {
        "ZABBIX_URL": "https://zabbix.example.com",
        "ZABBIX_USER": "api-user",
        "ZABBIX_PASSWORD": "",
        "ZABBIX_CATEGORIES_INI": "/path/to/categories.ini"
      }
    }
  }
}

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "zapi-mcp": {
      "command": "zapi-mcp",
      "env": {
        "ZABBIX_URL": "https://zabbix.example.com",
        "ZABBIX_USER": "api-user",
        "ZABBIX_PASSWORD": ""
      }
    }
  }
}

Codex

codex mcp add zapi-mcp \
  --env ZABBIX_URL=https://zabbix.example.com \
  --env ZABBIX_USER=api-user \
  --env ZABBIX_PASSWORD=your-password \
  --env ZABBIX_CATEGORIES_INI=/path/to/categories.ini \
  -- zapi-mcp

任何其他可启动 stdio 服务的 MCP 客户端也同样适用：将 zapi-mcp 设为命令，并在其环境中设置 ZABBIX_* 变量。

直接执行

export ZABBIX_URL=https://zabbix.example.com
export ZABBIX_USER=api-user
export ZABBIX_PASSWORD=your-password
# or, instead of the user and password: export ZABBIX_API_TOKEN=your-token
zapi-mcp

CLI 选项

zapi-mcp --version   # Print version and exit
zapi-mcp --check     # Verify environment variables and authentication, then exit
zapi-mcp --brief     # Print the daily_brief to stdout and exit (handy for cron)
zapi-mcp             # Start MCP server (STDIO, default)

--check 退出码：0 表示成功，1 表示配置错误，2 表示身份验证／连接错误。

--brief 退出码：0 表示成功，1 表示某个部分失败（身份验证、活动问题获取或类别加载——请查看输出中嵌入的 Error: 行）。

开发

git clone https://github.com/shigechika/zapi-mcp.git
cd zapi-mcp

# uv
uv sync --dev
uv run pytest -v
uv run ruff check .

# pip
python3 -m venv .venv
.venv/bin/pip install -e . && .venv/bin/pip install pytest pytest-cov respx ruff
.venv/bin/pytest -v
.venv/bin/ruff check .

实时冒烟测试

pytest 会使用固定数据检查逻辑；它无法判断工具是否已停止返回真实数据。scripts/smoke_test.py 会使用配置的 Zabbix 测试每个已注册工具，并在回答为空、格式错误或包含错误时失败：

# needs the same ZABBIX_* environment variables as the server
uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only get_problems --traceback

• 只读。 按名称跳过 acknowledge_problem 和 set_maintenance：确认操作对所有操作员都可见，且无法悄悄撤销；set_maintenance 则会开启真实的维护窗口并抑制告警。测试会确保这一点。报告只打印工具名称和状态，从不打印负载；服务器生成的错误文本也会被删去，因为 Zabbix 会引用被查询的主机。--traceback 仍会在操作员自己的终端上显示完整文本。
• 可能标识真实主机、组或标签值的参数会在运行时发现，绝不会写入 scripts/smoke_probes.py。两个测试会对此进行强制检查：一个拒绝将这些参数作为字面值，另一个禁止文件中出现任何类似地址的内容（邮件地址、URL、主机名、IPv4、IPv6）。
• 空回答在此处是有效的观察结果——监控系统没有任何异常才是我们的目标——因此探针会断言工具必须生成的封装结构，而非行数。
• CI 会强制执行成本较低的部分：注册了工具却没有探针规范会导致构建失败（tests/test_smoke_probes.py），因此每次新增工具都会促使我们思考“如何确认它能正常工作？”。
• scripts/smoke_harness.py 是执行引擎，不包含任何 Zabbix 知识：它在共用该引擎的服务之间保持完全一致，因此只需修复一次引擎错误，然后同步文件，而不是只修改此副本。

发布

发布通过 release-please 自动完成。将 Conventional Commits（feat:、fix:、……）合并到 main 后，会保持一个发布 PR 打开，其中包含下一个版本和变更日志。合并该 PR 后，会创建 vX.Y.Z 标签并发布 GitHub Release，其 release: published 事件会触发 release 工作流，构建并发布到 PyPI 和 MCP Registry。版本由 release-please 管理，位置在 zapi_mcp/__init__.py 和 server.json（请勿手动递增版本）。

重要

release-please 工作流应配置仓库密钥 RELEASE_PLEASE_TOKEN（一个拥有 contents: write + pull-requests: write 权限的 PAT）。 默认的 GITHUB_TOKEN 无法创建触发下游 release 工作流的 Release（GitHub 会阻止由 GITHUB_TOKEN 触发的工作流运行），因此没有 PAT 就不会发布任何内容。如果未设置该密钥，工作流会 回退到 GITHUB_TOKEN，以便分叉仓库上的 PR CI 继续正常工作。

路线图

• 为远程／移动场景提供 Streamable HTTP 传输 + OAuth2
• 关键指标的可视化呈现

许可证

MIT