zapi-mcp

<!-- mcp-name: io.github.shigechika/zapi-mcp -->

# zapi-mcp

English | [日本語](README.ja.md)

MCP (Model Context Protocol) server for the [Zabbix](https://www.zabbix.com/) 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

| Tool | Description |
|------|-------------|
| `health_check` | Server version, Zabbix connectivity/auth, detected API version, and configured `daily_brief` categories — call at session start or after a timeout |
| `daily_brief` | Morning patrol: active problems (Warning+), hosts currently in maintenance, plus one section per configured category |
| `get_problems` | Active problems by severity and tag, newest-first with age; header shows the true total (`showing N of TOTAL` when capped); problems on disabled triggers, hosts or items are hidden as in the Zabbix frontend (`include_disabled=True` lists them); output includes `eventid` |
| `get_hosts` | List hosts filtered by role/tag/group, with IP and tags |
| `get_host_items` | Current item values for a host (server-side host filter) |
| `acknowledge_problem` | Acknowledge problems and add a message (does not close them) |
| `set_maintenance` | Open an idempotent Zabbix maintenance window, selecting hosts by `location` tag or by exact host name (exactly one of the two) |
| `get_maintenance_windows` | List maintenance windows (Active/Upcoming/Expired) — cross-check before treating another tool's alert as a new incident |

## Setup

```bash
# uv
uv pip install zapi-mcp

# pip
pip install zapi-mcp
```

Or from source:

```bash
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:

| Variable | Description | Default |
|---|---|---|
| `ZABBIX_URL` | Zabbix base URL (e.g. `https://zabbix.example.com`); `/api_jsonrpc.php` is appended if absent | *required* |
| `ZABBIX_API_TOKEN` | Zabbix API token (Zabbix 5.4+), used instead of `ZABBIX_USER`/`ZABBIX_PASSWORD` | *one of the two* |
| `ZABBIX_USER` | Zabbix API user | *one of the two* |
| `ZABBIX_PASSWORD` | Zabbix API password | *one of the two* |
| `ZABBIX_CATEGORIES_INI` | Path to a categories INI file for `daily_brief` (optional) | — |
| `ZABBIX_BRIEF_RECENT_HOURS` | `daily_brief` "recent" window in hours; problems older than this are folded to a count | `24` |
| `ZABBIX_BRIEF_PROBLEM_LIMIT` | Max active problems `daily_brief` fetches per call before counting the rest | `1000` |
| `ZABBIX_READ_ONLY` | `true` (or `1`/`yes`/`on`) keeps `acknowledge_problem` and `set_maintenance` from being registered, so the model never sees them. Any other non-false value is also treated as read-only and reported by `health_check` | unset (write tools on) |

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:

```ini
[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`](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.

| Tool | Zabbix API call |
|---|---|
| `acknowledge_problem` | `event.acknowledge` |
| `set_maintenance` | `maintenance.create` |

`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 Claude for investigation without granting it any ability to change Zabbix
configuration. Grant the permission only when acknowledging alerts or opening
maintenance windows from Claude 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](#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](https://docs.astral.sh/uv/) system-wide if the plugin fails to start.

### Claude Code (manual)

Add to `.mcp.json`:

```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`:

```json
{
  "mcpServers": {
    "zapi-mcp": {
      "command": "zapi-mcp",
      "env": {
        "ZABBIX_URL": "https://zabbix.example.com",
        "ZABBIX_USER": "api-user",
        "ZABBIX_PASSWORD": ""
      }
    }
  }
}
```

### Direct Execution

```bash
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

```bash
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

```bash
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