Zabbix MCP Tools & API Patterns
Overview
Zabbix is self-hosted: every customer runs their own frontend, and the
Zabbix API is JSON-RPC at <frontend>/api_jsonrpc.php. The Zabbix MCP
server (zabbix-mcp, behind Conduit) exposes one read-only tool per
allowlisted *.get method. There are no write tools and no raw JSON-RPC
passthrough, because the same endpoint also serves every write method,
including script.execute. Problems are acknowledged, closed and suppressed
in the Zabbix frontend, never through this plugin.
Read this skill first; the other Zabbix skills assume these patterns.
Connection & Authentication
Conduit stores two fields per connection, entered in the Conduit web UI
(/connect/zabbix), and forwards them as headers. Nothing is set on the
client, and Conduit drops any X-Zabbix-* header a client sends:
| Conduit field |
Header |
| Zabbix frontend URL |
X-Zabbix-Base-Url |
| API token |
X-Zabbix-Api-Token |
- The frontend URL is the address users open Zabbix at (for example
https://zabbix.acme.com/zabbix), https only, no query string. Private,
loopback and metadata addresses are refused; an on-prem frontend needs
Conduit's egress IP allowlisted or a Conduit tunnel.
- The token is created in the frontend under Users > API tokens and is
64 letters and digits. It should belong to a dedicated user whose role can
only read the customer's host groups. Never a Super admin token: Super
admin can run
script.execute on every monitored agent.
- The sidecar calls
apiinfo.version (no credentials) and caches it for 10
minutes. Zabbix 6.4+ gets Authorization: Bearer; 6.0 and 6.2 get the
JSON-RPC body auth property. You never choose this.
zabbix_api_version is the connection test. It works even with a bad
token, so a successful version call proves only that the URL is right.
Follow it with a small zabbix_hostgroups_list call to prove the token.
Tool Surface
All tools are read tier. Conduit lists 18:
- Scoping:
zabbix_hostgroups_list, zabbix_hosts_list
- Problems and history:
zabbix_problems_list, zabbix_events_list,
zabbix_triggers_list, zabbix_alerts_list, zabbix_maintenance_list
- Coverage and collectors:
zabbix_templates_list, zabbix_proxies_list,
zabbix_proxy_groups_list, zabbix_web_scenarios_list
- Services and SLAs:
zabbix_services_list, zabbix_slas_list,
zabbix_sla_sli_get, zabbix_trends_get
- Other:
zabbix_api_version, zabbix_dashboards_list,
zabbix_auditlog_list
Admin-gated in Conduit
zabbix_auditlog_list is the only admin-gated tool: Conduit lets only
members with the admin permission tier call it. Zabbix additionally allows
auditlog.get only for Super admin tokens, so with the recommended
read-only token it fails with a permission error for everyone. Do not plan
a workflow around it.
Opt-in tools Conduit does not list
zabbix_items_list, zabbix_history_get and zabbix_host_interfaces_list
exist in the sidecar but are listed only when it runs with
ZABBIX_ENABLE_SENSITIVE_TOOLS=1, which Conduit's deployment does not set.
If they are absent from the tool list, that is expected. Use triggers and
problems for "what is wrong" and zabbix_trends_get (with item IDs from a
trigger or the frontend) for numeric history.
Shared Get Parameters
Most list tools share the standard Zabbix get parameters:
| Parameter |
Use |
output |
"extend" or an array of property names. Ask for only what you need; it keeps responses under the size cap. |
countOutput |
true returns a count instead of objects. Use it to size a query before pulling rows. |
limit |
1-500, default 100 on paged tools. Larger values are capped at 500, silently. |
sortfield / sortorder |
Sort field from the tool's allowed list; ASC or DESC. |
filter |
Exact match, e.g. {"status": 0} or {"value": 1}. |
search |
Case-insensitive substring, e.g. {"name": "web"}. Pair with searchWildcardsEnabled, startSearch, searchByAny, excludeSearch. |
tags / evaltype |
Tag filters, e.g. [{"tag":"customer","value":"contoso","operator":1}]. Operators: 0 contains, 1 equals, 2 does not contain, 3 does not equal, 4 exists, 5 does not exist. |
select* |
Include related objects, e.g. selectHostGroups: ["name"], selectTags: "extend". |
Input rules the sidecar enforces before calling Zabbix:
- IDs are digit strings (
"10084"), at most 500 per array.
- Time parameters accept Unix seconds or ISO 8601 (
2026-11-01T00:00:00Z).
- Severities are integers: 0 not classified, 1 information, 2 warning,
3 average, 4 high, 5 disaster.
- Unknown arguments are dropped, not sent.
- "Flag" parameters such as
monitored_hosts, only_true and
skipDependent are sent only when true. Passing false is the same as
leaving them out.
Paging
Zabbix has no offset paging and the sidecar never pages for you.
- Problems and events: sort by
eventid DESC, then pass the lowest
event ID you received minus one as eventid_till for the next page.
(eventid_from walks forward.)
- Alerts, trends, audit log: page by time with
time_from / time_till.
- Hosts, triggers, templates and the rest: there is no cursor. Use
countOutput first; if the count is over 500, narrow by groupids,
hostids, tags or search instead of trying to page.
Never report a list as complete when it came back with exactly limit rows.
Output Size and Redaction
- Tool output is capped (60,000 characters by default). Overflow ends with
[truncated: N more characters omitted ...]. If you see it, the answer is
incomplete: narrow output, limit, or the time range and query again.
- String values under secret-looking keys (password, passphrase, community,
psk, token, authorization) come back as
[REDACTED]. That is the sidecar,
not missing data.
- The sidecar never requests
selectMacros, selectItems on hosts and
templates, selectMediatypes, selectUsers or selectPreprocessing;
those parameters do not exist on these tools.
Errors
Errors come back as tool results starting with Error:.
| Error |
Cause |
Action |
Argument error ("hostids[0]" must be a numeric Zabbix ID, "sortfield" must be one of ...) |
Bad input, caught before Zabbix is called |
Fix the argument; nothing reached the customer's server |
| Auth error |
Token missing, malformed, expired, disabled, or rejected |
Reconnect Zabbix in Conduit with a valid token |
Zabbix JSON-RPC error -32602 (invalid params) |
Often an 8.0 parameter name on an older frontend, e.g. selectHostGroups on 6.0 |
Check zabbix_api_version; drop or rename the parameter |
Zabbix JSON-RPC error -32500 (application error), "no permissions" |
The token's role cannot read that object type or host group |
Expected for zabbix_auditlog_list; otherwise the role needs read access to that group |
| Unsafe base URL |
Frontend URL is http, private, a placeholder, or redirects |
Fix the URL in Conduit or route it through a tunnel |
| Timeout / unreachable |
Frontend down, or firewall blocks Conduit |
Check the frontend is up and Conduit's egress IP is allowed |
Rate Limits
Zabbix has no API rate limiting. Every call runs directly against the
customer's Zabbix database, so an unscoped zabbix_events_list over months
can hurt a small instance. Always scope by host group and time range, prefer
countOutput for counts, and do not fan out hundreds of per-host calls when
one call with hostids (up to 500) will do.
Related Skills
1---2name: zabbix-api-patterns3description: >4 Zabbix MCP fundamentals through Conduit: the X-Zabbix-Base-Url and5 X-Zabbix-Api-Token headers, version-dependent token auth, the read-only6 18-tool surface (one admin-gated tool, three opt-in tools Conduit does not7 list), the shared JSON-RPC get parameters (output, filter, search, tags,8 sortfield, limit), keyset paging by event ID or time range, the 500-row9 cap, output truncation and redaction, and the error types the sidecar10 returns.11when_to_use: >-12 When authenticating to or calling Zabbix through the MCP tools, shaping a13 get query, paging through results, or diagnosing a failed Zabbix request.14 Use when: zabbix api, zabbix token, zabbix connection, zabbix mcp, zabbix15 pagination, zabbix limit, zabbix error, zabbix permission error, or zabbix16 unexpected parameter.17metadata:18 source: https://skillmd.com/skills/wyre-ai/zabbix-api-patterns19---2021# Zabbix MCP Tools & API Patterns2223## Overview2425Zabbix is self-hosted: every customer runs their own frontend, and the26Zabbix API is JSON-RPC at `<frontend>/api_jsonrpc.php`. The Zabbix MCP27server (`zabbix-mcp`, behind Conduit) exposes one read-only tool per28allowlisted `*.get` method. There are no write tools and no raw JSON-RPC29passthrough, because the same endpoint also serves every write method,30including `script.execute`. Problems are acknowledged, closed and suppressed31in the Zabbix frontend, never through this plugin.3233Read this skill first; the other Zabbix skills assume these patterns.3435## Connection & Authentication3637Conduit stores two fields per connection, entered in the Conduit web UI38(`/connect/zabbix`), and forwards them as headers. Nothing is set on the39client, and Conduit drops any `X-Zabbix-*` header a client sends:4041| Conduit field | Header |42|---------------|--------|43| Zabbix frontend URL | `X-Zabbix-Base-Url` |44| API token | `X-Zabbix-Api-Token` |4546- The frontend URL is the address users open Zabbix at (for example47 `https://zabbix.acme.com/zabbix`), https only, no query string. Private,48 loopback and metadata addresses are refused; an on-prem frontend needs49 Conduit's egress IP allowlisted or a Conduit tunnel.50- The token is created in the frontend under **Users > API tokens** and is51 64 letters and digits. It should belong to a dedicated user whose role can52 only read the customer's host groups. **Never a Super admin token**: Super53 admin can run `script.execute` on every monitored agent.54- The sidecar calls `apiinfo.version` (no credentials) and caches it for 1055 minutes. Zabbix 6.4+ gets `Authorization: Bearer`; 6.0 and 6.2 get the56 JSON-RPC body `auth` property. You never choose this.57- `zabbix_api_version` is the connection test. It works even with a bad58 token, so a successful version call proves only that the URL is right.59 Follow it with a small `zabbix_hostgroups_list` call to prove the token.6061## Tool Surface6263All tools are read tier. Conduit lists 18:6465- **Scoping**: `zabbix_hostgroups_list`, `zabbix_hosts_list`66- **Problems and history**: `zabbix_problems_list`, `zabbix_events_list`,67 `zabbix_triggers_list`, `zabbix_alerts_list`, `zabbix_maintenance_list`68- **Coverage and collectors**: `zabbix_templates_list`, `zabbix_proxies_list`,69 `zabbix_proxy_groups_list`, `zabbix_web_scenarios_list`70- **Services and SLAs**: `zabbix_services_list`, `zabbix_slas_list`,71 `zabbix_sla_sli_get`, `zabbix_trends_get`72- **Other**: `zabbix_api_version`, `zabbix_dashboards_list`,73 `zabbix_auditlog_list`7475### Admin-gated in Conduit7677`zabbix_auditlog_list` is the only admin-gated tool: Conduit lets only78members with the `admin` permission tier call it. Zabbix additionally allows79`auditlog.get` only for Super admin tokens, so with the recommended80read-only token it fails with a permission error for everyone. Do not plan81a workflow around it.8283### Opt-in tools Conduit does not list8485`zabbix_items_list`, `zabbix_history_get` and `zabbix_host_interfaces_list`86exist in the sidecar but are listed only when it runs with87`ZABBIX_ENABLE_SENSITIVE_TOOLS=1`, which Conduit's deployment does not set.88If they are absent from the tool list, that is expected. Use triggers and89problems for "what is wrong" and `zabbix_trends_get` (with item IDs from a90trigger or the frontend) for numeric history.9192## Shared Get Parameters9394Most list tools share the standard Zabbix `get` parameters:9596| Parameter | Use |97|-----------|-----|98| `output` | `"extend"` or an array of property names. Ask for only what you need; it keeps responses under the size cap. |99| `countOutput` | `true` returns a count instead of objects. Use it to size a query before pulling rows. |100| `limit` | 1-500, default 100 on paged tools. Larger values are capped at 500, silently. |101| `sortfield` / `sortorder` | Sort field from the tool's allowed list; `ASC` or `DESC`. |102| `filter` | Exact match, e.g. `{"status": 0}` or `{"value": 1}`. |103| `search` | Case-insensitive substring, e.g. `{"name": "web"}`. Pair with `searchWildcardsEnabled`, `startSearch`, `searchByAny`, `excludeSearch`. |104| `tags` / `evaltype` | Tag filters, e.g. `[{"tag":"customer","value":"contoso","operator":1}]`. Operators: 0 contains, 1 equals, 2 does not contain, 3 does not equal, 4 exists, 5 does not exist. |105| `select*` | Include related objects, e.g. `selectHostGroups: ["name"]`, `selectTags: "extend"`. |106107Input rules the sidecar enforces before calling Zabbix:108109- IDs are digit strings (`"10084"`), at most 500 per array.110- Time parameters accept Unix seconds or ISO 8601 (`2026-11-01T00:00:00Z`).111- Severities are integers: 0 not classified, 1 information, 2 warning,112 3 average, 4 high, 5 disaster.113- Unknown arguments are dropped, not sent.114- "Flag" parameters such as `monitored_hosts`, `only_true` and115 `skipDependent` are sent only when `true`. Passing `false` is the same as116 leaving them out.117118## Paging119120Zabbix has no offset paging and the sidecar never pages for you.121122- **Problems and events**: sort by `eventid` `DESC`, then pass the lowest123 event ID you received minus one as `eventid_till` for the next page.124 (`eventid_from` walks forward.)125- **Alerts, trends, audit log**: page by time with `time_from` / `time_till`.126- **Hosts, triggers, templates and the rest**: there is no cursor. Use127 `countOutput` first; if the count is over 500, narrow by `groupids`,128 `hostids`, `tags` or `search` instead of trying to page.129130Never report a list as complete when it came back with exactly `limit` rows.131132## Output Size and Redaction133134- Tool output is capped (60,000 characters by default). Overflow ends with135 `[truncated: N more characters omitted ...]`. If you see it, the answer is136 incomplete: narrow `output`, `limit`, or the time range and query again.137- String values under secret-looking keys (password, passphrase, community,138 psk, token, authorization) come back as `[REDACTED]`. That is the sidecar,139 not missing data.140- The sidecar never requests `selectMacros`, `selectItems` on hosts and141 templates, `selectMediatypes`, `selectUsers` or `selectPreprocessing`;142 those parameters do not exist on these tools.143144## Errors145146Errors come back as tool results starting with `Error:`.147148| Error | Cause | Action |149|-------|-------|--------|150| Argument error (`"hostids[0]" must be a numeric Zabbix ID`, `"sortfield" must be one of ...`) | Bad input, caught before Zabbix is called | Fix the argument; nothing reached the customer's server |151| Auth error | Token missing, malformed, expired, disabled, or rejected | Reconnect Zabbix in Conduit with a valid token |152| Zabbix JSON-RPC error `-32602` (invalid params) | Often an 8.0 parameter name on an older frontend, e.g. `selectHostGroups` on 6.0 | Check `zabbix_api_version`; drop or rename the parameter |153| Zabbix JSON-RPC error `-32500` (application error), "no permissions" | The token's role cannot read that object type or host group | Expected for `zabbix_auditlog_list`; otherwise the role needs read access to that group |154| Unsafe base URL | Frontend URL is http, private, a placeholder, or redirects | Fix the URL in Conduit or route it through a tunnel |155| Timeout / unreachable | Frontend down, or firewall blocks Conduit | Check the frontend is up and Conduit's egress IP is allowed |156157## Rate Limits158159Zabbix has no API rate limiting. Every call runs directly against the160customer's Zabbix database, so an unscoped `zabbix_events_list` over months161can hurt a small instance. Always scope by host group and time range, prefer162`countOutput` for counts, and do not fan out hundreds of per-host calls when163one call with `hostids` (up to 500) will do.164165## Related Skills166167- [problem-triage](../problem-triage/SKILL.md) - NOC triage of open problems168- [monitoring-coverage](../monitoring-coverage/SKILL.md) - Hosts, templates, proxies, maintenance169- [sla-reporting](../sla-reporting/SKILL.md) - Services, SLAs, SLI and trends