工具和资源
概述
Zabbix MCP 服务器将 Zabbix 功能以工具和资源的形式提供给 MCP 客户端。
工具名称用于描述相应的活动。 如果设置了 ToolPrefix 参数，则此前缀会添加到每个工具名称中；工具访问规则匹配以下列出的原始名称。
读取工具
| 工具 | Zabbix API 方法 | 参数 | 排序依据 | 资源 |
|---|---|---|---|---|
hostgroup_get |
hostgroup.get | groupids、names、search、limit |
名称 | zabbix://hostgroup/<id> |
templategroup_get |
templategroup.get | groupids、names、search、limit |
名称 | zabbix://templategroup/<id> |
host_get |
host.get | hostids、groupids、search、limit |
名称 | zabbix://host/<id> |
template_get |
template.get | templateids、groupids、search、limit |
名称 | zabbix://template/<id> |
item_get |
item.get | hostids、itemids、search、limit |
名称 | zabbix://item/<id> |
lld_get |
discoveryrule.get | hostids、ruleids、limit |
名称 | - |
interface_get |
hostinterface.get | hostids、interfaceids、limit |
接口 ID | - |
macro_get |
usermacro.get | hostids 或 global、macro_names、limit |
宏 | - |
problem_get |
problem.get | eventids、groupids、hostids、severities、acknowledged、suppressed、recent、limit |
事件 ID，降序 | - |
maintenance_get |
maintenance.get | maintenanceids、groupids、hostids、limit |
名称 | - |
history_get |
history.get | itemids、time_from、time_till、type、limit |
时钟，降序 | - |
trigger_get |
trigger.get | triggerids、hostids、search、limit |
描述 | zabbix://trigger/<id> |
请注意：
host_get和template_get还会返回每个对象的触发器（字段集合有限）、标签和关联的模板。监控项、发现规则、接口和宏由相应的工具返回。history_get要求时间范围不超过 7 天，且开始时间不得早于 7 天前。type参数必须是float、unsigned、character、text、log或json之一，并且必须与监控项的值类型匹配；如果类型错误，将返回空结果，且无法将其与没有数据的监控项区分开来。无法通过 MCP 服务器检索二进制监控项（值类型 5）的历史数据。- 读取工具请求固定的字段列表；不会请求所有字段（
output: extend）。 - 包含资源的工具的结果包含
uri字段，因此 agent 可以从列表继续定位到单个实体。
响应格式
所有读取工具均以相同格式返回响应：
{
"results": [ ... ],
"count": 2,
"truncated": true,
"truncated_by": "count",
"limit": 2,
"note": "已达到结果数量限制 ..."
}响应受 limit 参数（默认值：100，最大值：1000）以及响应序列化大小（MaxResponseSize，默认值：64K）的限制。
达到任一限制时，响应将停止。
响应仅会在结果之间截断，不会在结果内部截断；截断的响应会指明达到的是哪个限制。
每个工具都有固定的排序顺序，因此截断的响应始终是完整结果集的开头部分。
不支持分页；如需获取其他结果，请缩小查询范围。
问题工具
所有问题工具都会使用相应的操作标志调用 event.acknowledge。
eventids 参数为必填项；可以使用 problem_get 获取事件 ID。
任何问题工具都可以添加消息（评论）。
除 problem_annotate 外，message 参数均为可选；对于 problem_annotate，该参数为必填项。如果指定了该参数，消息会在同一次 Zabbix API 调用中记录。
| 工具 | 效果 | 其他参数 |
|---|---|---|
problem_acknowledge |
确认问题。 | - |
problem_unacknowledge |
移除确认。 | - |
problem_close |
手动关闭问题（仅适用于允许手动关闭的触发器）。 | - |
problem_annotate |
记录消息。 | message（必填） |
problem_change_severity |
更改问题的严重性。 | severity（0-5） |
problem_suppress |
将问题抑制至指定时间，或无限期抑制。 | suppress_until |
problem_unsuppress |
移除抑制。 | - |
无法创建或删除问题；所有问题工具都会更新现有问题。
维护工具
| 工具 | Zabbix API 方法 | 参数 |
|---|---|---|
maintenance_create |
maintenance.create | name、groupids 和/或 hostids、active_since、active_till、timeperiods、description、tags、tags_evaltype |
maintenance_update |
maintenance.update | maintenanceid 以及上述任意参数。列表参数会替换整个值集合；空列表会清空该集合。 |
maintenance_delete |
maintenance.delete | maintenanceids |
更新维护周期时，列表参数（例如 hostids、groupids 和 timeperiods）会替换现有值，而不是将值添加到现有集合中。
例如，如果某个维护周期涵盖主机 A 和主机 B，而使用仅包含主机 C 的 hostids 调用 maintenance_update，则该维护周期将仅涵盖主机 C。
maintenance_create 是唯一不具备幂等性的操作，而 maintenance_delete 是唯一无法撤销的操作。
若要禁止使用这些操作，请通过 DenyTool 参数拒绝这些工具。
写入工具的行为
问题和维护工具属于写入工具。 其工作方式如下：
- 在调用任何 Zabbix API 之前，会先验证参数；如果验证失败，错误信息会指出未满足的约束条件。
- 如果客户端支持，只有在用户批准后才会应用更改。
- 更改由 Zabbix 使用调用方的令牌执行。Zabbix 会检查权限，并将更改以令牌所有者的身份记录在审计日志中。
- Zabbix 错误（包括权限错误）将作为包含
code、message和data字段的错误对象原样返回。 - 写入工具会直接返回 Zabbix 结果；读取工具的响应限制不适用。
- MCP 服务器绝不会重试写入调用。
资源
资源使用 zabbix://<kind>/<id> URI 方案。
resources/list 响应中仅包含 zabbix://about；无法枚举实体 ID，实体 ID 可从工具的结果中获取。
resources/templates/list 响应列出了实体的种类。
| URI | 内容 |
|---|---|
zabbix://about |
API URL、前端 URL、Zabbix 版本、调用方令牌解析到的身份，以及已公开工具的列表。 |
zabbix://host/<hostid> |
不包含监控项、触发器、接口和宏的主机记录。 |
zabbix://hostgroup/<groupid> |
不包含成员列表的主机组记录。 |
zabbix://template/<templateid> |
不包含监控项、触发器和发现规则的模板记录。 |
zabbix://templategroup/<groupid> |
不包含成员列表的模板组记录。 |
zabbix://item/<itemid> |
不包含当前值的监控项定义。 |
zabbix://trigger/<triggerid> |
不包含主机、依赖关系、函数和标签的触发器定义。 |
如果相应工具被拒绝访问，则对应资源不存在。
不存在的实体，以及令牌所有者无权访问的实体，都会报告为 resource not found；这些情况经过有意设计，无法相互区分。
zabbix://about 资源不受工具访问规则影响。