Zabbix AI CLI MCP — Zabbix MCP server and CLI for AI agents

zabbix-ai-cli-mcp is a Zabbix MCP server and command-line client in one Go binary. It gives Claude Code, Claude Desktop, Codex, Cursor and any other Model Context Protocol client task-shaped access to Zabbix — what is broken right now, why a host is silent, why an alert never arrived — with bounded output, a stable JSON contract, and no change to Zabbix without a person's approval.

It is for the people who get paged: SRE and DevOps teams running Zabbix who want an agent to triage an incident without handing it the whole API.

Requires Zabbix 6.4 or newer. Bearer-token authentication arrived in 6.4 and is the only scheme implemented; earlier versions expect the token in the request body instead.

It never contacts a language model. The AI decides, this program executes, Zabbix monitors.

zabbix-ai-cli-mcp login
zabbix-ai-cli-mcp problems list
zabbix-ai-cli-mcp host investigate server01
zabbix-ai-cli-mcp alert why 757474
zabbix-ai-cli-mcp mcp

Why not another Zabbix API wrapper

Wrapping host.get, problem.get and history.get hands the agent the API's sharp edges along with its power. On a current Zabbix 7.4 server:

• problem.get has no selectHosts, so a problem list arrives without hosts.
• history.get defaults to the numeric-unsigned table and returns nothing for a float item — silently, with no error.
• item.lastvalue and item.lastclock still exist and have returned a constant "0" for several major releases.
• host.available was removed in 5.4; availability lives on the interface.
• event.acknowledge takes a bitmask whose own documentation contradicts itself.
• searchWildcardsEnabled: true disables implicit substring matching, turning a name fragment into an exact match that quietly finds nothing.

Every one of those produces a confident, wrong answer rather than an error. This tool absorbs them behind commands that describe the task instead of the endpoint.

What it does

Safety

Read operations always run immediately. Whether anything else does is one setting, allow_write, and it is on by default.

# ~/.config/zabbix-ai-cli-mcp/config.toml
allow_write = true            # the default; omit the key and you get this

[profiles.prod]
url = "https://zabbix.example.com"
allow_write = false           # this one profile is an exception

If you are not sure, set allow_write = false. It costs one command per change and it is the right default for an installation you cannot afford to have an agent surprise you in. A profile override beats the file-wide setting, and ZABBIX_AI_CLI_MCP_ALLOW_WRITE beats both — that is how a container is told, without owning the config file.

With writes off, no tool and no flag applies anything: a change is described, and a person runs zabbix-ai-cli-mcp approve <plan-id> in their own terminal. A confirmation an agent could send would be a confirmation prompt injection could send, so none is offered — the approval lives outside the model's context.

With writes on, the agent applies the change itself and every change lands in an audit log with the profile, the parameters, the objects touched and whether a person or a model asked for it. zabbix-ai-cli-mcp mcp --read-only refuses both paths regardless of the setting, and an HTTP endpoint that can write refuses to start without a bearer token.

Everything else holds either way: a profile's scopes still bound what it may touch, the risk registry still refuses methods that hand out credentials or run code, and a plan is still re-checked against live Zabbix before it executes.

$ zabbix-ai-cli-mcp maintenance create "ms*" --for 2h

PLAN pl_cc89d2e87d15

Create maintenance "ms* (2h0m)" for 2h0m, 2026-08-21T05:39:00Z to 2026-08-21T07:39:00Z

Affects:
  host ms1.8qw.ru
  host ms10.8qw.ru
  ...

Risk: write
Expires: 2026-08-21T05:54:22Z

Nothing has changed yet.
To apply it: zabbix-ai-cli-mcp approve pl_cc89d2e87d15

Before a plan runs, its parameters are re-hashed, its deadline checked and its preconditions re-read from Zabbix. A window that has been replaced since the plan was made is refused, not deleted. Every applied change is appended to an audit log.

This matters more than a refusal would. When the tool this replaces blocked a write, the work was done anyway with a token copied out of a container — losing the audit trail without preventing anything. A permitted path that is recorded beats a refusal that gets routed around.

Install

Prebuilt archives and the ghcr.io image are published with each tagged release. Until the first tag lands, build from source with either method below.

For a host-native binary, use Go 1.25 or newer:

go install github.com/stufently/zabbix-ai-cli-mcp/cmd/zabbix-ai-cli-mcp@latest

# Or build the current checkout.
mkdir -p bin
go build -trimpath -o bin/zabbix-ai-cli-mcp ./cmd/zabbix-ai-cli-mcp

The Make targets are container-first and do not require Go on the host:

make build      # Linux binary in ./bin, built inside Docker
make docker     # Linux container image for the MCP server

Configure

zabbix-ai-cli-mcp login --profile prod

It asks for the URL and the API token, verifies the token against the server, and stores it. The token is never accepted as a flag, because flag values are visible in shell history and in the process list; pipe it in instead:

printf %s "$TOKEN" | zabbix-ai-cli-mcp login --profile prod --url https://zabbix.example.com --token-stdin

A profile that names no scopes may do anything the write setting allows. Naming any scope narrows it to exactly those:

zabbix-ai-cli-mcp profile scopes prod --add maintenance
zabbix-ai-cli-mcp profile show prod        # what it may do, writes included

See docs/authentication.md for the resolution order and the headless and container cases.

Add the Zabbix MCP server to your AI client

The MCP client never sees the Zabbix token. It is resolved inside the server process from the profile you configured, so the credential never enters a model's context or a client's configuration file.

Claude Code

claude mcp add zabbix -- zabbix-ai-cli-mcp mcp --profile prod
zabbix-ai-cli-mcp skills install claude

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "zabbix": {
      "command": "zabbix-ai-cli-mcp",
      "args": ["mcp", "--profile", "prod"]
    }
  }
}

Codex

# ~/.codex/config.toml
[mcp_servers.zabbix]
command = "zabbix-ai-cli-mcp"
args = ["mcp", "--profile", "prod"]

zabbix-ai-cli-mcp skills install codex

Cursor, Windsurf, VS Code and other MCP clients

Any client that speaks stdio takes the same two fields — command zabbix-ai-cli-mcp, arguments ["mcp", "--profile", "prod"]. For a client that wants HTTP instead:

zabbix-ai-cli-mcp mcp --http 127.0.0.1:8000 --bearer-token "$MCP_TOKEN"

A server that can write refuses to start on HTTP without a bearer token, even on loopback: without one, every process on the machine could change Zabbix through it. It refuses a routable address unless you pass --allow-remote together with a bearer token, because an unauthenticated MCP endpoint is an unauthenticated route into Zabbix. See docs/mcp.md.

Docker

docker run --rm -i \
  -e ZABBIX_AI_CLI_MCP_URL=https://zabbix.example.com \
  -e ZABBIX_AI_CLI_MCP_TOKEN_FILE=/run/secrets/zabbix \
  -v /path/to/token:/run/secrets/zabbix:ro \
  ghcr.io/stufently/zabbix-ai-cli-mcp:latest mcp

MCP tools

Fifteen tools, not two hundred. A large tool surface costs an agent context before it has done anything, and most of it is never called.