Zabbix MCP Server

Zabbix MCP Server with all functions and validations

- Query hosts and problems— Ask your assistant to check host availability, active problems, or trigger status using tools likehost_status_getandproblem_active_get.
- Generate infrastructure reports— Request a summary of your Zabbix environment, including host group overviews and item history trends, viainfrastructure_summary_getanditem_history_summary_get.
- Detect anomalies and forecast capacity— Useanomaly_detectfor z-score analysis on metrics andcapacity_forecastfor linear regression predictions on resource usage.
- Render graphs and export data— Ask for a PNG graph image withgraph_renderor generate a PDF report usingreport_generate.
- Manage templates and configurations— Instruct your assistant to export, import, or migrate Zabbix templates and hosts between servers, leveraging the full Zabbix API coverage.
- Perform write operations with approval— Useaction_prepareandaction_confirmto stage and confirm changes like acknowledgements or maintenance windows, with read-only mode protection.

developed and maintained byand community

Overview:What is this?·Features
Install:Quick Start·Installation·Upgrade·First-time admin access
Configure:Reference·OAuth 2.1·Public URL·TLS / HTTPS·Token Budget
Use:Client Wizard·AI Clients·Prompts·Tools·Parameters·PDF Reports
Operate:Installer CLI·Update notifications·Compatibility·Development·Related Projects·License

MCP(Model Context Protocol) is an open standard that lets AI assistants (ChatGPT, Claude, VS Code Copilot, JetBrains AI, Codex, and others) use external tools. This server exposes theentire Zabbix APIas MCP tools — allowing any compatible AI assistant to query hosts, check problems, manage templates, acknowledge events, and perform any other Zabbix operation.

- Complete API coverage- All 58 Zabbix API groups (223 tools): hosts, problems, triggers, templates, users, dashboards, and more
- Extension tools(14) -Pre-correlated views:host_status_get,hostgroup_overview_get,infrastructure_summary_get,item_history_summary_get,problem_active_get(fold 3-5 raw API calls into one round-trip). Plusgraph_render(PNG export),anomaly_detect(z-score analysis),capacity_forecast(linear regression),item_threshold_search(filter items bylastvaluethresholds),report_generate(PDF reports),action_prepare/action_confirm(two-step write approval),health_check(server diagnostics) andzabbix_raw_api_call(admin escape hatch for un-wrapped methods).
- Admin web portal- Full web UI on port 9090 for managing tokens, users, servers, templates, settings, and audit log; dark/light mode; point-and-clickClient MCP Wizard (beta)that generates copy-paste-ready config snippets for 14 AI clients (Claude, Codex, Cursor, Cline, VS Code, JetBrains, Goose, Open WebUI, 5ire, Gemini CLI, n8n, ...)
- Multi-token authentication- Named tokens with scopes, IP restrictions, server binding, expiry; managed via admin portal, CLI (generate-token), or config.toml
- Multi-server support- Connect to multiple Zabbix instances (production, staging, ...) with separate tokens
- HTTP + SSE transports- Streamable HTTP (recommended) and SSE for clients like n8n that lack session management
- Tool filtering- Limit exposed tools by category (monitoring,alerts,users,extensions, etc.) or individual API prefix to reduce the tool catalog size and stay under LLM context limits (seeToken Budgetbelow)
- Compact output mode- Get methods return only key fields by default, reducing response token usage; LLM can requestextendfor full details
- LLM-friendly normalizations- Symbolic enum names, auto-fill defaults, preprocessing cleanup, timestamp conversion
- Single config file- One TOML file, no scattered environment variables
- Read-only mode- Per-server and per-token write protection to prevent accidental changes
- Rate limiting- Per-client call budget (300/min default) to protect Zabbix from flooding
- Auto-reconnect- Transparent re-authentication on session expiry
- Production-ready- systemd service, logrotate, Docker support, security hardening
- Generic fallback-zabbix_raw_api_calltool for any API method not explicitly defined

git clone https://github.com/initMAX/zabbix-mcp-server.git cd zabbix-mcp-server sudo ./deploy/install.sh sudo nano /etc/zabbix-mcp/config.toml # fill in your Zabbix URL + API token sudo systemctl start zabbix-mcp-server sudo systemctl enable zabbix-mcp-server

Detailed guide:SeeINSTALL.mdfor step-by-step instructions for both on-prem (systemd) and Docker deployments, including uninstall, security checklist, and TLS setup.

- Linux server with Python 3.10+
- Network access to your Zabbix server(s)
- Zabbix API token (User settings > API tokens)

git clone https://github.com/initMAX/zabbix-mcp-server.git cd zabbix-mcp-server sudo ./deploy/install.sh

./deploy/install-user.sh # install ./deploy/install-user.sh update # git pull + pip + restart ./deploy/install-user.sh uninstall

cd zabbix-mcp-server sudo ./deploy/install.sh update

- /etc/zabbix-mcp/config.toml— your Zabbix URL, API token, MCP tokens, scopes, TLS settings, etc.
- Admin portal users (stored in[admin.users.]insideconfig.toml).
- Audit log, report templates, and any custom data.

You'll see✓ Config preserved at /etc/zabbix-mcp/config.toml (not overwritten)during the update. Checkconfig.example.tomlafterwards for any new options added in the release.

By defaultupdatekeeps your current reporting state — if PDF reporting was installed, it stays; if it wasn't, it is not added. To change that:

# Enable PDF reporting on an existing install that didn't have it sudo ./deploy/install.sh update --with-reporting # Update without PDF reporting dependencies (smaller install) sudo ./deploy/install.sh update --without-reporting

The--with-reportingflag pulls inweasyprint,jinja2, and system libs (cairo,pango,gdk-pixbuf). SeePDF Reportsfor what you get.

git fetch origin && git reset --hard origin/main sudo ./deploy/install.sh update

sudo ./deploy/install.sh test-config # validate config.toml sudo journalctl -u zabbix-mcp-server -n 50 --no-pager

[server] transport = "http" host = "127.0.0.1" port = 8080 [zabbix.production] url = "https://zabbix.example.com" api_token = "your-api-token" read_only = true verify_ssl = true

All available options with detailed descriptions are documented inconfig.example.toml.

┌────────────┐ MCP token (Bearer) ┌──────────────────┐ api_token ┌───────────────┐ │ MCP Client ├──────────────────────► MCP Server ├─────────────────► Zabbix Server │ │ (AI / IDE) │ (optional) │ (zabbix-mcp) │ (required) │ │ └────────────┘ │ │ └───────────────┘ │ Admin Portal │ │ :9090 (optional) │ └──────────────────┘

api_token(in[zabbix.]) —required— authenticates the MCP server to your Zabbix instance. This is aZabbix API tokenthat you create in the Zabbix frontend.
- In Zabbix frontend:Users → API tokens → Create API token
- Select the user the token will belong to
- Optionally set an expiration date
- Copy the generated token — it is shown only once

# Generate a token via installer sudo ./deploy/install.sh generate-token claude # Or generate manually python3 -c "import secrets,hashlib; t='zmcp_'+secrets.token_hex(32); print(f'Token: {t}\nHash: sha256:{hashlib.sha256(t.encode()).hexdigest()}')"

[tokens.claude] name = "Claude Code" token_hash = "sha256:<paste hash>" scopes = [""] # or specific: ["monitoring", "alerts"] read_only = true

Each token can have independent scopes, IP restrictions, server binding, and expiry. Seeconfig.example.tomlfor all options.

[server] auth_token = "your-secret-token-here"

Legacyauth_tokenis automatically migrated to[tokens.legacy]on first v1.16 start.

When no tokens are configured, the server accepts unauthenticated connections. This is safe when bound to127.0.0.1(default) butmust be configuredwhen exposed to the network (0.0.0.0).

OAuth 2.1(v1.28+) — for clients that auto-discover authentication (ChatGPT custom apps, Claude Desktop remote, MCP Inspector). Enable with:

[server] public_url = "https://mcp.example.com" # required when OAuth is on [oauth] enabled = true

Login uses the existing admin-portal users. Dynamic client registration (RFC 7591) is on by default; ChatGPT's "Advanced OAuth settings" auto-detects everything from the.well-known/...discovery documents. The legacy[tokens.X]bearer mode keeps working alongside OAuth - existing CLI scripts and workflow tools need no change.

Full setup, security checklist, and troubleshooting indocs/OAUTH.md.

[zabbix.production] url = "https://zabbix.example.com" api_token = "prod-token" read_only = true [zabbix.staging] url = "https://zabbix-staging.example.com" api_token = "staging-token" read_only = false

The first server (production) is used as the default. To target a specific instance, just mention it naturally in your prompt:

The AI assistant maps your natural language to the correctserverparameter automatically — no need to use technical syntax likeserver = "staging"in your prompts.

The MCP server itself isstateless— there is no shared state between instances. You can run multiple MCP server instances behind a reverse proxy (nginx, HAProxy, Caddy) using round-robin load balancing. Each instance connects to Zabbix independently.

Note:When your Zabbix runs in HA mode with multiple frontends, the API is available on each frontend. Currently the MCP server connects to a singleurlper[zabbix.<name>]entry. Multi-frontend failover (connecting to multiple URLs for the same Zabbix instance) is a planned feature.

sudo systemctl start zabbix-mcp-server sudo systemctl enable zabbix-mcp-server

The server exposes two health check mechanisms:

# Simple HTTP health check (no authentication needed) curl http://localhost:8080/health # → {"status":"ok"}

Use the HTTP/healthendpoint for load balancer probes, uptime monitoring, and container orchestration readiness checks. Use thehealth_checkMCP tool for deeper diagnostics including Zabbix server connectivity.

The application writes to the log file configured inconfig.toml(log_file). Startup errors before logging initialization go to the systemd journal.

# Live log stream (application log) tail -f /var/log/zabbix-mcp/server.log # Via journalctl (startup errors + fallback) sudo journalctl -u zabbix-mcp-server -f

Web-based administration portal for managing MCP tokens, users, report templates, and server settings. Runs on aseparate port(default: 9090) — the MCP port (8080) serves only the MCP protocol, no admin UI.

The installer generates an admin password automatically. To reset:sudo ./deploy/install.sh set-admin-password

All changes are written back toconfig.toml(preserving comments and formatting via tomlkit). Every config change triggers a "Restart needed" indicator.

Beta- introduced in v1.20 with 14 supported clients and wide test coverage, but we are still collecting real-world feedback on the per-client snippets, the OAuth-vs-Bearer handling (especially Claude Desktop + ChatGPT), and edge cases around Docker / NAT / reverse-proxy host overrides. Please report issues athttps://github.com/initMAX/zabbix-mcp-server/issuesso we can graduate it out of beta.

A standalone page at/wizard(sidebar entryClient MCP Wizard) that replaces hand-editing JSON / TOML config files for 14 AI clients. Single-page progressive disclosure in four steps:
- Pick a Zabbix server- cards list all[zabbix.*]entries fromconfig.toml.
- Pick an MCP token- cards show every token whoseallowed_serversincludes the chosen server, plus per-token scope chips (groups + individual prefixes), IP restrictions, and expiry. When the MCP server is in no-auth mode, aContinue without tokencard generates a tokenless snippet; when auth is enabled, the+ Create new tokencard chains into/tokens/create?return_to=/wizardand comes back with the new token pre-filled via a URL fragment (never sent to the server).
- Pick your AI client- grid of 14 cards: Claude Desktop, Claude Code (CLI), OpenAI Codex, ChatGPT, VS Code + GitHub Copilot, Cursor, Cline, JetBrains AI, Goose, Open WebUI, 5ire, Gemini CLI, n8n, Generic MCP Client.
- Copy the config- host override picker when[server].host = 0.0.0.0(Docker container IPs are de-emphasized with a manual-entry input on top), transport picker with a "detected" badge on the running transport, per-client install instructions on the left, syntax-highlighted snippet on the right with a copy-on-hover overlay icon, download-as-file button, and a matching curl quick-test block. Both code blocks substitute a pasted Bearer token live so the operator can verify before copying.

Every snippet and instruction set comes from a single-source-of-truth catalog (src/zabbix_mcp/admin/wizard_clients.py) cross-checked against each client's current official documentation (Claude Desktop viamcp-remotewrapper for Bearer tokens, Claude Code with the--transport/--headerflag rename from 2025, ChatGPT Developer-mode Apps & Connectors path, Gemini CLIhttpUrlvsurlkey split, Goose Streamable HTTP YAML schema, Open WebUI native MCP since v0.6.31, etc.).

Port separation:MCP endpoint (/mcp,/health) runs exclusively on the MCP port (default 8080). Admin portal runs exclusively on the admin port (default 9090). No admin API is exposed on the MCP port. Firewall both ports independently.

git clone https://github.com/initMAX/zabbix-mcp-server.git cd zabbix-mcp-server cp config.example.toml config.toml nano config.toml # fill in your Zabbix details cp .env.example .env # optional: customize port, host, auth token docker compose up -d

The config file is mounted read-write into the container (admin portal writes changes back). Logs are stored in a Docker volume.

Customizing the port and host interface— create a.envfile (copy from.env.example) and set:

MCP_HOST=127.0.0.1 # interface to bind on the Docker host (default: 127.0.0.1) MCP_PORT=8080 # port used inside the container and exposed on the host (default: 8080) MCP_AUTH_TOKEN=... # bearer token for MCP server authentication (optional)