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

# uvuv pip install zapi-mcp
# pippip install zapi-mcp

Or from source:

git clone https://github.com/shigechika/zapi-mcp.gitcd zapi-mcp
# uvuv sync
# pippip 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 grouptag = dhcp-pool-usage# report current values for this exact item keyitem_key = usage# flag values >= thisthreshold = 80
[snat]name = SNAT Session Pooltag = snat-pool-usage# substring match (catches pool.node0.usage etc.)item_key_search = .usagethreshold = 80
[core]name = Core Networktag = role# the tag must equal this valuetag_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.comexport ZABBIX_USER=api-userexport ZABBIX_PASSWORD=your-password# or, instead of the user and password: export ZABBIX_API_TOKEN=your-tokenzapi-mcp

CLI Options

zapi-mcp --version   # Print version and exitzapi-mcp --check     # Verify environment variables and authentication, then exitzapi-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.gitcd zapi-mcp
# uvuv sync --devuv run pytest -vuv run ruff check .
# pippython3 -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 serveruv run python scripts/smoke_test.pyuv 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 tool forces the question "how would we know it works?".
• scripts/smoke_harness.py is the engine and holds no Zabbix knowledge: it is kept identical across the servers that share it, so fix engine bugs once and sync the file rather than patching this copy.

Releasing

Releases are automated with release-please. Merging Conventional Commits (feat:, fix:, …) to main keeps a release PR open with the next version and changelog. Merging that PR tags vX.Y.Z and publishes a GitHub Release, whose release: published event triggers the release workflow to build and publish to PyPI and the MCP Registry. release-please owns the version in zapi_mcp/__init__.py and server.json (do not bump them by hand).

[!IMPORTANT] The release-please workflow should be given a repository secret RELEASE_PLEASE_TOKEN (a PAT with contents: write + pull-requests: write). The default GITHUB_TOKEN cannot create the Release that triggers the downstream release workflow (GitHub blocks workflow runs triggered by GITHUB_TOKEN), so without the PAT nothing gets published. The workflow falls back to GITHUB_TOKEN when the secret is unset so PR CI keeps working on forks.

Roadmap

• Streamable HTTP transport + OAuth2 for remote / mobile use
• Visual rendering of key metrics

License

MIT