Zabbix MCP server
Commit Nov 13, 2026Exposes the complete Zabbix API as MCP tools, allowing AI assistants to query hosts, manage templates, and monitor infrastructure.
Also known as initMAX/zabbix-mcp-server
- Stars
- 251
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 13, 2026
- License
- AGPL-3.0
What is Zabbix MCP?
Zabbix exposes the complete Zabbix API as MCP tools, allowing AI assistants to query hosts, manage templates, and monitor infrastructure.
Summary generated from the project's README
About Zabbix MCP server
Monitoring infrastructure through AI assistants is possible with this server, which exposes the entire Zabbix API as a set of tools. It allows users to query hosts, check active problems, manage templates, and acknowledge events using clients like Claude, VS Code, JetBrains, and Cursor. The server operates as a standalone HTTP service that connects to your Zabbix instances via API tokens.
Beyond standard API access, it includes specialized extension tools for complex tasks. These include capacity forecasting using linear regression, anomaly detection via z-score analysis, and graph rendering for PNG exports. It also features a built-in admin web portal on port 9090 to manage tokens, users, and audit logs. To prevent accidental changes, administrators can enable read-only mode for specific tokens or servers.
Developers can manage the tool catalog using tool filtering to stay within LLM context limits. The server also provides compact output modes to reduce token usage and includes a generic fallback tool for any Zabbix API method not explicitly wrapped. It supports multi-server configurations, allowing a single installation to communicate with multiple Zabbix environments like production and staging.
What you can do with it
- 1Manage Zabbix configurationsUse an AI assistant to query hosts, manage templates, and check active problems.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
MCP_AUTH_TOKENMCP_HOSTMCP_PORTZABBIX_MCP_TOKENZABBIX_OLD_PASSWORD
Automated checks
Ran Nov 13, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packageNot checked
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesNot checked
README
View on GitHubTable of Contents
What is this?
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 the entire Zabbix API as MCP tools — allowing any compatible AI assistant to query hosts, check problems, manage templates, acknowledge events, and perform any other Zabbix operation.
The server runs as a standalone HTTP service. AI clients connect to it over the network.
Features
- Complete API coverage - All 68 Zabbix API groups (241 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-click Client 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 (see Token Budget below) - Compact output mode - Get methods return only key fields by default, reducing response token usage; LLM can request
extendfor full details - LLM-friendly normalizations - Symbolic enum names, auto-fill defaults, preprocessing cleanup, timestamp conversion with local-time rendering (
<field>_localsiblings and a per-call zone note, see Time zones) - Single config file - One TOML file, no scattered environment variables
- Read-only mode - Per-server and per-token write protection to prevent accidental changes
- Honest tool hints - Every tool says whether it reads, only adds, overwrites or removes, and whether a repeat is harmless (MCP tool annotations), so a client can ask before the right calls
- No silent wrong answers - A parameter the method or the tool does not have is refused with the place the value belongs,
falsefor a Zabbix flag is not sent, and a log read with a limit returns its newest rows - Rate limiting - Per-client call budget (300/min default) to protect Zabbix from flooding
- Auto-reconnect - Transparent re-authentication on session expiry; a read whose answer was lost is asked again, a write is never sent twice
- Production-ready - systemd service, logrotate, Docker support, security hardening
- Generic fallback -
zabbix_raw_api_calltool for any API method not explicitly defined
Quick Start
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 --now zabbix-mcp-initmax # starts zabbix-mcp-server at boot, see Start below
Done. The server is running on http://127.0.0.1:8080/mcp.
Installation
Detailed guide: See
INSTALL.mdfor step-by-step instructions for both on-prem (systemd) and Docker deployments, including uninstall, security checklist, and TLS setup.
Requirements
- Linux server with Python 3.10+
- Network access to your Zabbix server(s)
- A Zabbix API token (User settings > API tokens). Zabbix 5.0 and 5.2 have no API tokens; for those two releases only, an explicit legacy password login exists - see Legacy auth and read the warning there first
Install
git clone https://github.com/initMAX/zabbix-mcp-server.git
cd zabbix-mcp-server
sudo ./deploy/install.sh
The install script will:
- Create a dedicated system user
zabbix-mcp(no login shell) - Create a Python virtual environment in
/opt/zabbix-mcp/venv - Install the server and all dependencies
- Copy the example config to
/etc/zabbix-mcp/config.toml - Install a systemd service unit (
zabbix-mcp-server) - Set up logrotate for
/var/log/zabbix-mcp/*.log(daily, 30 days retention) - Verify file permissions and offer to fix any issues
User-mode install (no root, dev / laptop use)
For developers running the server locally on their own machine, an alternative installer is shipped that does not require sudo:
./deploy/install-user.sh # install
./deploy/install-user.sh update # git pull + pip + restart
./deploy/install-user.sh uninstall
It detects Python 3.10+, creates a virtualenv inside the repo, copies config.example.toml to config.toml (with log_file rewritten to a user-writable path), and registers a background service:
- macOS - LaunchAgent at
~/Library/LaunchAgents/com.initmax.zabbix-mcp-server.plist(auto-restart viaKeepAlive) - Linux - systemd
--userunit at~/.config/systemd/user/zabbix-mcp-server.servicewithloginctl enable-lingerso the service survives logout
This is intended for local development. For production servers use the regular sudo ./deploy/install.sh above.
Upgrade
cd zabbix-mcp-server
sudo ./deploy/install.sh update
That's the whole procedure — no manual steps afterwards. From v1.15+ the update command handles git sync, package reinstall, systemd reload, validation, and service restart in one shot.
What update does:
- Pulls latest code from the current branch (fast-forward; falls back to
fetch + reset --hard origin/<branch>if history diverged), then re-executes itself from the updated script. - Reinstalls the Python package into
/opt/zabbix-mcp/venv. - Refreshes the systemd unit and logrotate config (in case they changed between releases).
- Checks file permissions and offers to fix any ownership issues.
- Runs small migrations (legacy token, report templates) and validates
config.toml— aborts if the config is invalid. - Restarts the service via
systemctl restart zabbix-mcp-serverand performs an HTTP health check on the configured port.
What is preserved (never overwritten):
/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. Check config.example.toml afterwards for any new options added in the release.
PDF reporting during update:
By default update keeps 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-reporting flag pulls in weasyprint, jinja2, and system libs (cairo, pango, gdk-pixbuf). See PDF Reports for what you get.
Upgrading from very old versions (pre-v1.15)? If
updatefails, do a one-time manual sync first:git fetch origin && git reset --hard origin/main sudo ./deploy/install.sh updateTroubleshooting: if something goes wrong, inspect:
sudo ./deploy/install.sh test-config # validate config.toml sudo journalctl -u zabbix-mcp-server -n 50 --no-pager
Configure
Edit the config file with your Zabbix server details:
sudo nano /etc/zabbix-mcp/config.toml
Minimal configuration - just fill in your Zabbix URL and API token:
[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 in config.example.toml.
Authentication — two tokens explained
The config file contains two different types of tokens that serve different purposes:
┌────────────┐ 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.*]) — authenticates the MCP server to your Zabbix instance. This is a Zabbix API token that you create in the Zabbix frontend. It is required. The only exception is the explicit legacy password login for Zabbix 5.0 and 5.2 - see Legacy auth.
How to create one:
- 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
The token inherits the permissions of the Zabbix user it belongs to:
| Use case | Recommended Zabbix role | read_only config |
|---|---|---|
| Read-only monitoring (problems, hosts, dashboards) | User role with read access to needed host groups | true |
| Full management (create hosts, templates, triggers) | Admin role with read-write access to target host groups | false |
| Complete API access (users, settings, global scripts) | Super admin role | false |
Use the principle of least privilege — create a dedicated Zabbix user for the MCP server with only the permissions it needs.
Legacy auth (Zabbix 5.0 and 5.2 only)
Read this before enabling it. Zabbix 5.0 and 5.2 are out of upstream support and have no API tokens - they were introduced in 5.4. The only way in is a username and password, which means this server holds a user password in its configuration instead of a revocable, scoped token. That is a security risk you are choosing to carry, and this project treats the whole path as best effort: it is not in our test matrix and we cannot verify it against a live 5.x. The right fix is upgrading Zabbix. If you cannot yet, this exists so you are not locked out in the meantime.
It has to be switched on explicitly. A username/password pair without the flag is a configuration error, not a fallback:
[zabbix.old-prod]
url = "https://zabbix5.example.com"
legacy_auth = true # the switch - Zabbix 5.0 / 5.2 only
username = "zabbix-mcp" # dedicated low-privilege account
password = "${ZABBIX_OLD_PASSWORD}" # keep it in the environment, not the file
read_only = true
Rules the server enforces:
legacy_auth = trueandapi_tokenon the same entry is refused - one credential per server, nothing inferred.username/passwordwithoutlegacy_auth = trueis refused.- Version lock: on connect the server reads
apiinfo.versionand refuses legacy login against anything 5.4 or newer. On a current Zabbix the flag does nothing except fail loudly, so it cannot be used to avoid tokens where they exist. - Every start logs a
WARNINGfor each legacy entry naming the Zabbix version, so the choice stays visible in the operational log. - The admin portal shows the same warning on the server card and in the Add / Edit form, and the password is never sent back to the browser.
The session from user.login expires; the server re-authenticates automatically when Zabbix answers that it has. Use a dedicated Zabbix user with only the permissions the tools need, and read_only = true unless writes are genuinely required.
Keeping the password out of the config file: username and password support ${ENV_VAR} expansion. Under Docker, put the variable in .env (the compose file injects it via env_file):
# .env
ZABBIX_OLD_PASSWORD=your-password-here
The zabbix-utils library this server uses refuses Zabbix below 6.0 by default; the version check is relaxed only for entries marked legacy_auth, never for token authentication.
MCP Authentication (optional)
Protects the MCP server from unauthorized access. When configured, MCP clients must include a bearer token in every request: Authorization: Bearer <token>.
Recommended: Multi-token system (v1.16+) — generate tokens via installer, admin portal, or manually:
# 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()}')"
Then add to config.toml:
[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, expiry, and time zone (timezone = "Europe/London", see Time zones). See config.example.toml for all options.
Legacy: Single auth_token — still supported for backward compatibility:
[server]
auth_token = "your-secret-token-here"
Legacy
auth_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 to 127.0.0.1 (default) but must be configured when 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 in docs/OAUTH.md.
Multiple Zabbix servers
You can connect to multiple Zabbix instances. Each tool has a server parameter to select which one to use (defaults to the first defined):
[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. One exception: when the MCP token making the call is restricted through allowed_servers, the default for the call is one of its own servers (the global default if it is among them, else the first listed), so per-user or per-customer tokens, each pointing at its own [zabbix.<name>] entry, work without naming the server every time. Such a token also sees only its own servers: the server parameter in tools/list and the "Unknown Zabbix server" message name nothing else (since v1.41, MSP setups where the instance name is the customer name). To target a specific instance, just mention it naturally in your prompt:
Prompt examples
| Prompt | Target server | What happens |
|---|---|---|
| "Show me hosts with high CPU usage" | production (default) |
Queries the first defined server automatically |
| "Show me hosts in our staging Zabbix instance" | staging |
AI recognizes "staging" and routes to the matching server |
| "What are the top triggers in the last hour on production?" | production |
Explicit mention of "production" confirms the default |
| "Compare trigger counts between production and staging" | both | AI queries both servers and combines the results |
| "Create a maintenance window on staging for tonight" | staging |
Write operation routed to staging (requires read_only = false) |
| "Acknowledge all disaster problems on production" | production |
Write operation on production (blocked if read_only = true) |
| "Export the 'Linux by Zabbix agent' template from production" | production |
Read-only export, works even with read_only = true |
| "Import this template to staging" | staging |
Write operation routed to staging |
| "Migrate host 'web-01' from production to staging" | both | AI reads from production, creates on staging |
The AI assistant maps your natural language to the correct server parameter automatically — no need to use technical syntax like server = "staging" in your prompts.
High Availability
The MCP server itself is stateless — 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 single
urlper[zabbix.<name>]entry. Multi-frontend failover (connecting to multiple URLs for the same Zabbix instance) is a planned feature.
Start
sudo systemctl start zabbix-mcp-server
sudo systemctl enable --now zabbix-mcp-initmax
Verify the server is running:
sudo systemctl status zabbix-mcp-server
zabbix-mcp-initmax is a second unit that the installer writes next to the server's own. It does nothing by itself: it starts zabbix-mcp-server at boot, and enabling or disabling it enables or disables both. start, stop and restart work under either name, and under the alias zabbix-mcp once the unit is enabled; the status and the journal are the server's, under zabbix-mcp-server. The second name is there because zabbix-mcp-server.service is also the unit name of the MCP server that Zabbix 8.0 packages, and that package's install and removal scripts enable, disable, start and stop whatever unit carries the name: see The MCP server shipped with Zabbix 8.0. On a host without that package systemctl enable zabbix-mcp-server works as before; install.sh update switches an installation that was enabled that way over to zabbix-mcp-initmax.
Health Check
The server exposes two health check mechanisms:
| Method | Endpoint | Auth required | Returns |
|---|---|---|---|
| HTTP endpoint | GET /health |
No | {"status": "ok"} — confirms the HTTP server is running |
| MCP tool | health_check |
Yes (if auth_token set) | Full connectivity status of each configured Zabbix server |
Quick check from the command line:
# Simple HTTP health check (no authentication needed)
curl http://localhost:8080/health
Zabbix MCP questions
What can I do with the Zabbix MCP server?
It allows AI assistants to query hosts, check problems, manage templates, acknowledge events, and perform any other Zabbix operation via the full API.
Does it support multiple Zabbix instances?
Yes, the server supports multi-server connectivity, allowing you to connect to multiple Zabbix instances like production and staging using separate tokens.
Can I restrict the AI from making changes to my Zabbix server?
Yes, you can enable a read-only mode per-server and per-token to prevent accidental changes.
What kind of authentication does it use?
The server supports multi-token authentication with named tokens, scopes, and IP restrictions, as well as OAuth 2.1 and bearer auth.