Zabbix AI CLI

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

[CI] [Go Reference] [License] [Zabbix] [MCP]

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 one setting, allow_write, that decides whether the agent applies a change or a person approves a plan.

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 loginzabbix-ai-cli-mcp problems listzabbix-ai-cli-mcp host investigate server01zabbix-ai-cli-mcp alert why 757474zabbix-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.tomlallow_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: writeExpires: 2026-08-21T05:54:22Z
Nothing has changed yet.To apply it: zabbix-ai-cli-mcp approve pl_cc89d2e87d15

Media channel state and lost LLD resource policies also use this approval/audit path. Media state requests are idempotent for external cron use; LLD plans show host scope and lost-item counts and flag history deletion as destructive. See parameters and examples.

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

On Linux or macOS, paste this into a terminal. It fetches the latest release, checks it against checksums.txt, puts the binary in ~/.local/bin and starts the MCP server over stdio. Replace the two placeholders first:

VERSION=$(curl -fsSLI -o /dev/null -w '%{url_effective}' \  https://github.com/stufently/zabbix-ai-cli-mcp/releases/latest | sed 's|.*/v||')OS=$(uname -s | tr '[:upper:]' '[:lower:]')                      # linux | darwinARCH=$(uname -m | sed 's/x86_64/amd64/; s/aarch64/arm64/')        # amd64 | arm64ARCHIVE=zabbix-ai-cli-mcp_${VERSION}_${OS}_${ARCH}.tar.gzBASE=https://github.com/stufently/zabbix-ai-cli-mcp/releases/download/v${VERSION}
TMP=$(mktemp -d) && cd "$TMP"curl -fsSLO "$BASE/$ARCHIVE" && curl -fsSLO "$BASE/checksums.txt"grep " $ARCHIVE\$" checksums.txt | shasum -a 256 -c -   # sha256sum -c - works tootar -xzf "$ARCHIVE"mkdir -p ~/.local/bin && install -m 0755 zabbix-ai-cli-mcp ~/.local/bin/~/.local/bin/zabbix-ai-cli-mcp --versionZABBIX_AI_CLI_MCP_URL=https://zabbix.example.com ZABBIX_AI_CLI_MCP_TOKEN=your-api-token ~/.local/bin/zabbix-ai-cli-mcp mcp

The last line is the command every client block below runs: zabbix-ai-cli-mcp with arguments ["mcp"], the Zabbix URL and API token taken from the environment. Stop it with Ctrl-C once it starts; the client launches it from then on. ~/.local/bin has to be on PATH, because the client configurations call the binary by name; otherwise give them the absolute path.

Prebuilt binary (no Go needed)

Each tagged release publishes archives for Linux, macOS and Windows on amd64 and arm64, plus checksums.txt. The block at the top of this section installs one on Linux or macOS. The archive also carries docs/ and the agent skills.

On Windows (PowerShell), the archive is a zip:

$Version = (Invoke-RestMethod https://api.github.com/repos/stufently/zabbix-ai-cli-mcp/releases/latest).tag_name.TrimStart('v')$Arch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'arm64' } else { 'amd64' }$Zip = "zabbix-ai-cli-mcp_${Version}_windows_${Arch}.zip"$Base = "https://github.com/stufently/zabbix-ai-cli-mcp/releases/download/v$Version"Invoke-WebRequest "$Base/$Zip" -OutFile $ZipInvoke-WebRequest "$Base/checksums.txt" -OutFile checksums.txt$Want = ((Select-String -Path checksums.txt -Pattern " $Zip$").Line -split '\s+')[0]if ((Get-FileHash $Zip -Algorithm SHA256).Hash -ne $Want) { throw "checksum mismatch" }Expand-Archive $Zip -DestinationPath "$env:LOCALAPPDATA\zabbix-ai-cli-mcp" -Force& "$env:LOCALAPPDATA\zabbix-ai-cli-mcp\zabbix-ai-cli-mcp.exe" --version

Add %LOCALAPPDATA%\zabbix-ai-cli-mcp to PATH, or use the full path to zabbix-ai-cli-mcp.exe in the client configuration.

From source

For a host-native build, 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 bingo 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 Dockermake docker     # Linux container image for the MCP server

Check where a release came from

checksums.txt proves a download is intact, not who built it: whoever could replace an archive could replace the checksum file next to it. From the first release cut after this section was added, the release workflow also signs build provenance for every archive, every .mcpb bundle and the container image (Sigstore, through GitHub artifact attestations). With the GitHub CLI:

verify() {  gh attestation verify "$1" --repo stufently/zabbix-ai-cli-mcp \    --source-ref "refs/tags/v$VERSION" \    --signer-workflow stufently/zabbix-ai-cli-mcp/.github/workflows/release.yml \    --deny-self-hosted-runners}verify "$ARCHIVE"verify "zabbix-ai-cli-mcp-${VERSION}-linux-amd64.mcpb"verify "oci://ghcr.io/stufently/zabbix-ai-cli-mcp:$VERSION"

A pass means the file was built by this repository's release workflow, on a GitHub-hosted runner, from the tag v$VERSION: an attested file from another release, renamed, fails --source-ref. Releases up to and including 0.4.3 carry checksums only.

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 maintenancezabbix-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

Each block below runs zabbix-ai-cli-mcp with arguments ["mcp"], the same command as the install line above. The URL and the API token are placeholders in env: replace them, and do not commit a real token. If you would rather keep the token out of the client, run zabbix-ai-cli-mcp login and pass --profile plus the profile name in args instead of those two variables.

Claude Code

Project file .mcp.json, at the root of the project:

{  "mcpServers": {    "zabbix": {      "command": "zabbix-ai-cli-mcp",      "args": ["mcp"],      "env": {        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"      }    }  }}

The same server can be registered from a terminal. Set the two variables in the environment that launches Claude Code, or rely on the .mcp.json above:

claude mcp add zabbix -- zabbix-ai-cli-mcp mcpzabbix-ai-cli-mcp skills install claude

Claude Desktop

claude_desktop_config.json — macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json, Linux ~/.config/Claude/claude_desktop_config.json:

{  "mcpServers": {    "zabbix": {      "command": "zabbix-ai-cli-mcp",      "args": ["mcp"],      "env": {        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"      }    }  }}

Claude Desktop can also install this server in one click. Download the .mcpb for your operating system from https://github.com/stufently/zabbix-ai-cli-mcp/releases/latest and open it. Desktop asks for the Zabbix URL, the API token, and whether writes are allowed (off by default in the Desktop extension). See docs/mcp.md.

The same release publishes checksums.txt with the SHA256 of every .mcpb. Download that file into the same directory as the bundle and check it before opening the bundle:

sha256sum -c --ignore-missing checksums.txt   # run next to the downloaded .mcpb

On macOS, filter the bundle's line and check it with shasum -a 256 -c -.

Cursor

[Add zabbix MCP server to Cursor]

The button runs zabbix-ai-cli-mcp from your PATH (see Install); after installing, put your URL and token in place of the placeholders in ~/.cursor/mcp.json. Or add the block below by hand.

~/.cursor/mcp.json, or .cursor/mcp.json in the project:

{  "mcpServers": {    "zabbix": {      "command": "zabbix-ai-cli-mcp",      "args": ["mcp"],      "env": {        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"      }    }  }}

Windsurf

mcp_config.json. On macOS and Linux that is ~/.config/devin/mcp_config.json (or $XDG_CONFIG_HOME/devin/mcp_config.json). On Windows it is %APPDATA%\devin\mcp_config.json. Older builds used ~/.codeium/windsurf/mcp_config.json.

{  "mcpServers": {    "zabbix": {      "command": "zabbix-ai-cli-mcp",      "args": ["mcp"],      "env": {        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"      }    }  }}

Zed

Zed calls MCP servers context servers. The file is settings.json (zed: open settings file):

{  "context_servers": {    "zabbix": {      "command": "zabbix-ai-cli-mcp",      "args": ["mcp"],      "env": {        "ZABBIX_AI_CLI_MCP_URL": "https://zabbix.example.com",        "ZABBIX_AI_CLI_MCP_TOKEN": "your-api-token"      }    }  }}

The same entry can be made from Settings → AI → MCP Servers → Add Server → Add Local Server; the indicator next to the server's name there shows whether it started.

Codex

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

zabbix-ai-cli-mcp skills install codex

VS Code

Any other stdio client takes the same command zabbix-ai-cli-mcp and arguments ["mcp"], plus the URL and token in the environment. 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.

zabbix_problems           zabbix_metrics_latest      zabbix_unreachablezabbix_problem            zabbix_metrics_history     zabbix_maintenance_listzabbix_hosts              zabbix_alert_why           zabbix_api_callzabbix_host_status        zabbix_resolve             zabbix_plan_createzabbix_host_investigate                              zabbix_plan_status                                                     zabbix_write

Write operations do not get one tool each. zabbix_write and zabbix_plan_create take an operation enum generated from the same registry the CLI is built from, so the tool surface does not grow as operations are added. zabbix_write is offered only where allow_write permits it.

Example prompts

• Why did the disk alert on web01 never arrive?
• What is broken in Zabbix right now?
• Which monitored hosts has Zabbix been unable to poll?
• How did CPU on db01 look over the last day?

JSON contract

{  "ok": true,  "data": {},  "warnings": [],  "meta": {    "returned": 50,    "total": 381,    "truncated": true,    "truncated_reason": "row_limit",    "partial": false,    "zabbix_version": "7.4.10"  }}

Errors carry a stable code, whether retrying is worthwhile, and what to do next:

{  "ok": false,  "error": {    "code": "AUTHENTICATION_FAILED",    "message": "Zabbix rejected the configured API token",    "retryable": false,    "suggestion": "run 'zabbix-ai-cli-mcp login' to configure a new token"  }}

zabbix-ai-cli-mcp schema prints every operation, its parameters and its JSON Schema, so an agent can learn the tool programmatically instead of guessing at flags.

Full details in docs/json-output.md.

Documentation

• Authentication and profiles
• Command line
• MCP server
• Skills
• JSON output and exit codes
• Security model
• Architecture and design decisions

FAQ

What is a Zabbix MCP server?

An MCP server is a small program that exposes a system to an AI client over the Model Context Protocol. A Zabbix MCP server lets Claude, Codex, Cursor and similar clients query Zabbix — problems, hosts, items, events, maintenance — as tools, instead of the model guessing at curl calls against the JSON-RPC API.

Can an AI agent change my Zabbix through this?

That is yours to decide, and the setting is allow_write. Left alone it is on, and an agent can open a maintenance window or acknowledge an event itself — every change audited, and bounded by the profile's scopes and the risk registry.

Set allow_write = false and it cannot. A write then produces a plan and stops; applying it is a command you run in your own terminal, zabbix-ai-cli-mcp approve <plan-id>. No MCP parameter applies anything in that mode, and a test fails the build if one is ever added.

Does it send my monitoring data to an AI provider?

No. This program never contacts a language model. It talks to Zabbix and prints JSON. Whatever your MCP client does with that output is between you and your client.

Which Zabbix versions are supported?

Zabbix 6.4 and newer, because bearer-token authentication arrived in 6.4. Developed and tested against Zabbix 7.4.

Do I need Go installed?

No. make build compiles inside Docker and needs nothing on the host but Docker itself. go install is there for a host-native binary, and each tagged release publishes archives for Linux, macOS and Windows with checksums, along with a container image on ghcr.io.

How is this different from an MCP server that wraps the Zabbix API?

A thin wrapper hands the agent the API's sharp edges: problem.get without hosts, history.get silently returning nothing for float items, lastvalue frozen at "0". Those produce confident wrong answers rather than errors. This tool answers questions — "what is broken", "why did this alert not arrive" — and absorbs the traps behind them. It also ships fifteen tools rather than two hundred, because a large tool surface spends an agent's context before it does any work.

Can I still call the raw Zabbix API?

Yes, through api call, under the same rules as everything else. Methods that hand out credentials or execute code are refused outright — including the long way round, such as creating a script and having an action run it.

Does it work without an AI client at all?

Yes. It is a normal CLI with human-readable tables, JSON output and documented exit codes, so it is equally usable from a shell or a CI job.

Tested clients and platforms

Only what has actually been run is listed. The client blocks above for Claude Desktop, Cursor, Windsurf, Zed and VS Code follow each client's documented MCP configuration and have not been exercised by the maintainer; reports are welcome.

Compatibility

Zabbix 6.4 and newer. Bearer-token authentication arrived in 6.4 and is the only scheme implemented. Version-dependent behaviour is asserted explicitly, so an incompatibility is reported rather than returning an empty result.

Developed and tested against Zabbix 7.4.

License

Apache-2.0. See LICENSE.

Zabbix is a trademark of Zabbix LLC. This project is an independent open-source project and is not affiliated with or endorsed by Zabbix LLC.