{
  "markdown": "<!-- mcp-name: io.github.shigechika/zapi-mcp -->\n\n# zapi-mcp\n\nEnglish | [日本語](README.ja.md)\n\nMCP (Model Context Protocol) server for the [Zabbix](https://www.zabbix.com/) API.\n\nBuilt for network operations: a single `daily_brief` call summarizes active\nproblems plus site-specific categories (DHCP pool usage, SNAT session usage,\ncore-network problems, …), and individual tools query problems, hosts, and item\nvalues. Organization-specific tags live in a config file, not the code, so the\nserver stays generic.\n\nVersion-adaptive auth: works against Zabbix 6.0 LTS (`user` + `auth` field) and\nforward-compatible with 6.4 / 7.0 (`username` + `Authorization: Bearer`).\n\nDocumentation: <https://shigechika.github.io/zapi-mcp/>\n\n## Features\n\n| Tool | Description |\n|------|-------------|\n| `health_check` | Server version, Zabbix connectivity/auth, detected API version, and configured `daily_brief` categories — call at session start or after a timeout |\n| `daily_brief` | Morning patrol: active problems (Warning+), hosts currently in maintenance, plus one section per configured category |\n| `get_problems` | Active problems by severity and tag, newest-first with age; header shows the true total (`showing N of TOTAL` when capped); output includes `eventid` |\n| `get_hosts` | List hosts filtered by role/tag/group, with IP and tags |\n| `get_host_items` | Current item values for a host (server-side host filter) |\n| `acknowledge_problem` | Acknowledge problems and add a message (does not close them) |\n| `set_maintenance` | Open an idempotent Zabbix maintenance window, selecting hosts by `location` tag or by exact host name (exactly one of the two) |\n| `get_maintenance_windows` | List maintenance windows (Active/Upcoming/Expired) — cross-check before treating another tool's alert as a new incident |\n\n## Setup\n\n```bash\n# uv\nuv pip install zapi-mcp\n\n# pip\npip install zapi-mcp\n```\n\nOr from source:\n\n```bash\ngit clone https://github.com/shigechika/zapi-mcp.git\ncd zapi-mcp\n\n# uv\nuv sync\n\n# pip\npip install -e .\n```\n\n## Configuration\n\nSet the following environment variables:\n\n| Variable | Description | Default |\n|---|---|---|\n| `ZABBIX_URL` | Zabbix base URL (e.g. `https://zabbix.example.com`); `/api_jsonrpc.php` is appended if absent | *required* |\n| `ZABBIX_USER` | Zabbix API user | *required* |\n| `ZABBIX_PASSWORD` | Zabbix API password | *required* |\n| `ZABBIX_CATEGORIES_INI` | Path to a categories INI file for `daily_brief` (optional) | — |\n| `ZABBIX_BRIEF_RECENT_HOURS` | `daily_brief` \"recent\" window in hours; problems older than this are folded to a count | `24` |\n| `ZABBIX_BRIEF_PROBLEM_LIMIT` | Max active problems `daily_brief` fetches per call before counting the rest | `1000` |\n\nThe API user needs read permission for the host groups you query, plus\nacknowledge permission if you use `acknowledge_problem`, maintenance-write\npermission if you use `set_maintenance`, and maintenance-read permission\n(usually included by default) for `get_maintenance_windows` and the\n`daily_brief` \"In Maintenance\" section.\n\n### Active problems in `daily_brief`\n\nProblems are grouped by severity and listed **newest-first**, each annotated with\nits age (e.g. `3h ago`). Problems older than the recent window\n(`ZABBIX_BRIEF_RECENT_HOURS`, default 24h) are folded to a single\n`… and N older (stale; oldest …)` line — so a backlog of alerts that Zabbix\nkeeps active because their recovery is never auto-confirmed (ICMP ping down, RDP\ndown, …) doesn't bury what just happened. Section headers carry the true total\nand show `showing N of TOTAL` when the fetch is capped, never a silent truncation.\n\n### Maintenance windows in `daily_brief`\n\nRight after Active Problems, `daily_brief` lists hosts covered by a\nmaintenance window that's active now, plus any window starting later today —\nso a planned outage isn't mistaken for a new incident by whatever else is\nwatching those hosts. The `## In Maintenance` section is omitted entirely\nwhen there's nothing to show (no news is no maintenance). Windows starting\ntomorrow or later, and expired windows, aren't included here; call\n`get_maintenance_windows` (optionally with `include_expired=True`) for the\nfull picture.\n\n### Categories for `daily_brief` (optional)\n\n`daily_brief` always lists active problems. To add site-specific sections —\nDHCP pool exhaustion, SNAT session usage, core-network problems — point\n`ZABBIX_CATEGORIES_INI` at an INI file. Each `[section]` is one category:\n\n```ini\n[dhcp]\nname = DHCP Pool Usage\n# Zabbix host tag identifying the group\ntag = dhcp-pool-usage\n# report current values for this exact item key\nitem_key = usage\n# flag values >= this\nthreshold = 80\n\n[snat]\nname = SNAT Session Pool\ntag = snat-pool-usage\n# substring match (catches pool.node0.usage etc.)\nitem_key_search = .usage\nthreshold = 80\n\n[core]\nname = Core Network\ntag = role\n# the tag must equal this value\ntag_value = main\n# no item key -> report active problems instead\n```\n\n- `tag` (required): host tag identifying the category. With `tag_value`, the tag\n  must equal it (Equal); without, any host carrying the tag matches (Exists).\n- `item_key` / `item_key_search`: when either is set, the section reports current\n  item values sorted high-to-low. `item_key` matches the key exactly; use\n  `item_key_search` for keys that embed an id (e.g. `.usage` catches\n  `pool.node0.usage`). When neither is set, it reports active problems for the tag.\n- `threshold`: optional; values at or above it are flagged.\n\nSee [`categories.ini.example`](categories.ini.example). When the variable is\nunset or the file is missing, `daily_brief` reports active problems only.\n\n### Write operations\n\nTwo tools change state. Everything else only reads.\n\n| Tool | Zabbix API call |\n|---|---|\n| `acknowledge_problem` | `event.acknowledge` |\n| `set_maintenance` | `maintenance.create` |\n\n`acknowledge_problem` needs acknowledge permission on the API user;\n`set_maintenance` needs maintenance-write permission. **Leave either off and\nthe server stays read-only for that one tool**: the call fails against the\nZabbix API and every other tool keeps working, so an API user can be handed\nto Claude for investigation without granting it any ability to change Zabbix\nconfiguration. Grant the permission only when acknowledging alerts or opening\nmaintenance windows from Claude is part of the job.\n\n## Usage\n\n### Claude Code (plugin)\n\nThis repository doubles as a single-plugin marketplace, so Claude Code can\ninstall the server for you:\n\n```\n/plugin marketplace add shigechika/zapi-mcp\n/plugin install zapi-mcp@zapi-mcp\n```\n\nThe plugin launches `uvx zapi-mcp` and reads the same environment variables\ndescribed in [Configuration](#configuration); export them before starting\nClaude Code. `ZABBIX_CATEGORIES_INI` may stay unset.\n\n`uvx` must be on the `PATH` of the process that runs Claude Code — a login\nshell usually has it, but a GUI-launched app may not; install\n[uv](https://docs.astral.sh/uv/) system-wide if the plugin fails to start.\n\n### Claude Code (manual)\n\nAdd to `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zapi-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"zapi-mcp\",\n      \"env\": {\n        \"ZABBIX_URL\": \"https://zabbix.example.com\",\n        \"ZABBIX_USER\": \"api-user\",\n        \"ZABBIX_PASSWORD\": \"\",\n        \"ZABBIX_CATEGORIES_INI\": \"/path/to/categories.ini\"\n      }\n    }\n  }\n}\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zapi-mcp\": {\n      \"command\": \"zapi-mcp\",\n      \"env\": {\n        \"ZABBIX_URL\": \"https://zabbix.example.com\",\n        \"ZABBIX_USER\": \"api-user\",\n        \"ZABBIX_PASSWORD\": \"\"\n      }\n    }\n  }\n}\n```\n\n### Direct Execution\n\n```bash\nexport ZABBIX_URL=https://zabbix.example.com\nexport ZABBIX_USER=api-user\nexport ZABBIX_PASSWORD=your-password\nzapi-mcp\n```\n\n### CLI Options\n\n```bash\nzapi-mcp --version   # Print version and exit\nzapi-mcp --check     # Verify environment variables and authentication, then exit\nzapi-mcp --brief     # Print the daily_brief to stdout and exit (handy for cron)\nzapi-mcp             # Start MCP server (STDIO, default)\n```\n\n`--check` exit codes: `0` success, `1` config error, `2` auth/connection error.\n\n`--brief` exit codes: `0` success, `1` a section failed (auth, the active-problems\nfetch, or category loading — see the embedded `Error:` line in the output).\n\n## Development\n\n```bash\ngit clone https://github.com/shigechika/zapi-mcp.git\ncd zapi-mcp\n\n# uv\nuv sync --dev\nuv run pytest -v\nuv run ruff check .\n\n# pip\npython3 -m venv .venv\n.venv/bin/pip install -e . && .venv/bin/pip install pytest pytest-cov respx ruff\n.venv/bin/pytest -v\n.venv/bin/ruff check .\n```\n\n### Live smoke test\n\n`pytest` checks logic against fixtures; it cannot tell you that a tool has\nstopped returning real data. `scripts/smoke_test.py` runs **every registered\ntool** against the configured Zabbix and fails on empty, malformed or error\nanswers:\n\n```bash\n# needs the same ZABBIX_* environment variables as the server\nuv run python scripts/smoke_test.py\nuv run python scripts/smoke_test.py --only get_problems --traceback\n```\n\n- **Read-only.** `acknowledge_problem` and `set_maintenance` are skipped by\n  name — an acknowledgement is visible to every operator and cannot be\n  quietly undone, and `set_maintenance` opens a real maintenance window that\n  suppresses alerts — and a test enforces that. The report prints tool names\n  and statuses only, never\n  payloads; server-authored error text is redacted too, since Zabbix quotes the\n  host it was asked about. `--traceback` still shows the full text on the\n  operator's own terminal.\n- Arguments that would identify real hosts, groups or tag values are\n  **discovered at run time**, never written into `scripts/smoke_probes.py`.\n  Two tests enforce that: one refuses those parameters as literals, the other\n  bans anything address-shaped (mail address, URL, hostname, IPv4, IPv6)\n  anywhere in the file.\n- An empty answer is a real observation here — a monitoring system with nothing\n  wrong is the goal — so probes assert the envelope the tool must produce\n  rather than a row count.\n- CI enforces the cheap half: a tool registered without a probe spec fails the\n  build (`tests/test_smoke_probes.py`), so adding a tool forces the question\n  \"how would we know it works?\".\n- `scripts/smoke_harness.py` is the engine and holds no Zabbix knowledge: it is\n  kept identical across the servers that share it, so fix engine bugs once and\n  sync the file rather than patching this copy.\n\n## Releasing\n\nReleases are automated with [release-please](https://github.com/googleapis/release-please).\nMerging [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, …)\nto `main` keeps a release PR open with the next version and changelog. Merging\nthat PR tags `vX.Y.Z` and publishes a GitHub Release, whose `release: published`\nevent triggers the `release` workflow to build and publish to PyPI and the MCP\nRegistry. release-please owns the version in `zapi_mcp/__init__.py` and\n`server.json` (do not bump them by hand).\n\n> [!IMPORTANT]\n> The release-please workflow should be given a repository secret\n> `RELEASE_PLEASE_TOKEN` (a PAT with `contents: write` + `pull-requests: write`).\n> The default `GITHUB_TOKEN` cannot create the Release that triggers the\n> downstream `release` workflow (GitHub blocks workflow runs triggered by\n> `GITHUB_TOKEN`), so without the PAT nothing gets published. The workflow falls\n> back to `GITHUB_TOKEN` when the secret is unset so PR CI keeps working on forks.\n\n## Roadmap\n\n- Streamable HTTP transport + OAuth2 for remote / mobile use\n- Visual rendering of key metrics\n\n## License\n\nMIT\n",
  "bytes": 11599,
  "sha": "10844a33839e254ca9d18ac6b75894e129fcb4b5638083705b71f242766234fa",
  "repo_slug": "shigechika/zapi-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shigechika_zapi_mcp_a636aaa8/readme"
}