Setup¶

Install¶

uv pip install zapi-mcp
# or
pip install zapi-mcp

From source:

git clone https://github.com/shigechika/zapi-mcp.git
cd zapi-mcp
uv sync          # or: pip install -e .

Zabbix account¶

The API user needs read permission on the host groups you query, plus acknowledge permission if you intend to use acknowledge_problem and maintenance-write permission if you intend to use set_maintenance. Nothing else is required — no super-admin role, no other write access to configuration.

Leave either permission off and that one tool fails against the Zabbix API while every other tool keeps working — see the acknowledge_problem and set_maintenance entries in the Reference for the exact API call each one makes.

Creating a dedicated API user rather than reusing a person's account keeps the audit trail readable and survives that person leaving.

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 for `daily_brief`	—
`ZABBIX_BRIEF_RECENT_HOURS`	`daily_brief` "recent" window in hours; older problems 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)

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.

Verify before wiring it into anything

zapi-mcp --check

Exit 0 means the environment is complete and authentication succeeded; 1 is a config error, 2 an auth or connection error. Running this once turns "the tool returns nothing" into a question you have already answered.

Register with an MCP client¶

Claude Code (plugin)¶

This repository doubles as a single-plugin marketplace:

/plugin marketplace add shigechika/zapi-mcp
/plugin install zapi-mcp@zapi-mcp

The plugin launches uvx zapi-mcp and reads the same environment variables as every other transport; export them before starting Claude Code.

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)¶

.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¶

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

Zabbix version compatibility¶

Authentication is version-adaptive: the client detects the API version and sends user + auth field against 6.0 LTS, or username + Authorization: Bearer against 6.4 and 7.0. No configuration selects this — an upgrade of the Zabbix server needs no change here.

health_check reports the detected version in zabbix_api_version, which is the quickest way to confirm what the server actually answered with.

Next¶

Add site-specific sections to the morning report: Categories for daily_brief.