Zabbix API MCP

zapi-mcp

English | 日本語

MCP (Model Context Protocol) server for the Zabbix API.

Built for network operations: a single daily_brief call summarizes active problems plus site-specific categories (DHCP pool usage, SNAT session usage, core-network problems, …), and individual tools query problems, hosts, and item values. Organization-specific tags live in a config file, not the code, so the server stays generic.

Version-adaptive auth: works against Zabbix 6.0 LTS (user + auth field) and forward-compatible with 6.4 / 7.0 (username + Authorization: Bearer).

Documentation: https://shigechika.github.io/zapi-mcp/

Features

Setup

# uv

uv pip install zapi-mcp

pip

pip install zapi-mcp

Or from source:

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

cd zapi-mcp

uv

uv sync

pip

pip install -e .

Configuration

Set the following environment variables:

The API user needs read permission for the host groups you query, plus acknowledge permission if you use acknowledge_problem, maintenance-write permission if you use set_maintenance, and maintenance-read permission (usually included by default) for get_maintenance_windows and the daily_brief "In Maintenance" section.

Authenticate with either ZABBIX_API_TOKEN or ZABBIX_USER + ZABBIX_PASSWORD. When a token is set, a leftover ZABBIX_USER is ignored; a token together with both ZABBIX_USER and ZABBIX_PASSWORD is a configuration error. A token needs no login and keeps a password out of the client configuration; it can be given an expiry and revoked on its own on Zabbix's API tokens page.

Active problems in daily_brief

Problems are grouped by severity and listed newest-first, each annotated with its age (e.g. 3h ago). Problems older than the recent window (ZABBIX_BRIEF_RECENT_HOURS, default 24h) are folded to a single … and N older (stale; oldest …) line — so a backlog of alerts that Zabbix keeps active because their recovery is never auto-confirmed (ICMP ping down, RDP down, …) doesn't bury what just happened. Section headers carry the true total and show showing N of TOTAL when the fetch is capped, never a silent truncation.

Maintenance windows in daily_brief

Right after Active Problems, daily_brief lists hosts covered by a maintenance window that's active now, plus any window starting later today — so a planned outage isn't mistaken for a new incident by whatever else is watching those hosts. The ## In Maintenance section is omitted entirely when there's nothing to show (no news is no maintenance). Windows starting tomorrow or later, and expired windows, aren't included here; call get_maintenance_windows (optionally with include_expired=True) for the full picture.

Categories for daily_brief (optional)

daily_brief always lists active problems. To add site-specific sections — DHCP pool exhaustion, SNAT session usage, core-network problems — point ZABBIX_CATEGORIES_INI at an INI file. Each [section] is one category:

[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 (required): host tag identifying the category. With tag_value, the tag must equal it (Equal); without, any host carrying the tag matches (Exists).
• item_key / item_key_search: when either is set, the section reports current item values sorted high-to-low. item_key matches the key exactly; use item_key_search for keys that embed an id (e.g. .usage catches pool.node0.usage). When neither is set, it reports active problems for the tag.
• threshold: optional; values at or above it are flagged.

See categories.ini.example. When the variable is unset or the file is missing, daily_brief reports active problems only.

Write operations

Two tools change state. Everything else only reads.

acknowledge_problem needs acknowledge permission on the API user; set_maintenance needs maintenance-write permission. Leave either off and the server stays read-only for that one tool: the call fails against the Zabbix API and every other tool keeps working, so an API user can be handed to an AI assistant for investigation without granting it any ability to change Zabbix configuration. Grant the permission only when acknowledging alerts or opening maintenance windows through the assistant is part of the job.

To keep the write tools away from the model altogether, set ZABBIX_READ_ONLY=true: the two tools are not registered, so a client never sees them, and they refuse to run if called anyway. This lets one Zabbix user serve both a read-only and a write-enabled MCP client. Every tool also carries MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint), so a client can tell read and write tools apart.

Usage

Claude Code (plugin)

This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:

/plugin marketplace add shigechika/zapi-mcp

/plugin install zapi-mcp@zapi-mcp

The plugin launches uvx zapi-mcp and reads the same environment variables described in Configuration; export them before starting Claude Code. ZABBIX_CATEGORIES_INI may stay unset.

uvx must be on the PATH of the process that runs Claude Code — a login shell usually has it, but a GUI-launched app may not; install uv system-wide if the plugin fails to start.

Claude Code (manual)

Add to .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

Add to 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

Any other MCP client that launches stdio servers works the same way: give it zapi-mcp as the command and set the ZABBIX_* variables in its environment.

Direct Execution

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 Options

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 exit codes: 0 success, 1 config error, 2 auth/connection error.

--brief exit codes: 0 success, 1 a section failed (auth, the active-problems fetch, or category loading — see the embedded Error: line in the output).

Development

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 .

Live smoke test

pytest checks logic against fixtures; it cannot tell you that a tool has stopped returning real data. scripts/smoke_test.py runs every registered tool against the configured Zabbix and fails on empty, malformed or error answers:

# 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

• Read-only. acknowledge_problem and set_maintenance are skipped by name — an acknowledgement is visible to every operator and cannot be quietly undone, and set_maintenance opens a real maintenance window that suppresses alerts — and a test enforces that. The report prints tool names and statuses only, never payloads; server-authored error text is redacted too, since Zabbix quotes the host it was asked about. --traceback still shows the full text on the operator's own terminal.
• Arguments that would identify real hosts, groups or tag values are discovered at run time, never written into scripts/smoke_probes.py. Two tests enforce that: one refuses those parameters as literals, the other bans anything address-shaped (mail address, URL, hostname, IPv4, IPv6) anywhere in the file.
• An empty answer is a real observation here — a monitoring system with nothing wrong is the goal — so probes assert the envelope the tool must produce rather than a row count.
• CI enforces the cheap half: a tool registered without a probe spec fails the build (tests/test_smoke_probes.py), so adding a