Mcp Zabbix

MCP Zabbix

A production-grade Model Context Protocol server that bridges the Zabbix monitoring API with AI assistants such as Claude Desktop, Cursor, and any other MCP-compatible client. Built on FastMCP with an async httpx client, typed Pydantic models, structured logging, and a trend-graph renderer that returns both an on-disk PNG and a base64 payload for inline display.

---

Table of contents

• Architecture
• Highlights
• Available tools
• Project layout
• Quick start
  • Local (pip)
  • Local (uv)
  • Docker
• Configuration
• MCP client setup
• Usage examples
• Development
• License

---

Architecture

                       ┌─────────────────────────────────────┐
                       │       AI Assistant / MCP Client     │
                       │   (Claude Desktop, Cursor, etc.)    │
                       └────────────────┬────────────────────┘
                                        │
                                        │   MCP stdio (JSON-RPC)
                                        ▼
        ┌──────────────────────────────────────────────────────────┐
        │                   FastMCP server (main.py)               │
        │  ┌────────────────────────────────────────────────────┐  │
        │  │  @mcp.tool registrations  →  async handlers        │  │
        │  └────────────────────────────────────────────────────┘  │
        │            │                  │                 │        │
        │            ▼                  ▼                 ▼        │
        │  ┌──────────────────┐  ┌────────────┐  ┌──────────────┐  │
        │  │  ZabbixClient    │  │  Email     │  │  Graph       │  │
        │  │  (httpx async,   │  │  (smtplib  │  │  (matplotlib │  │
        │  │   retry, auth)   │  │   thread)  │  │   PNG+b64)   │  │
        │  └────────┬─────────┘  └─────┬──────┘  └──────┬───────┘  │
        │           │                  │                │          │
        │  ┌────────┴──────────────────┴────────────────┴──────┐   │
        │  │  core/  : Settings  •  Logger  •  Exceptions      │   │
        │  └───────────────────────────────────────────────────┘   │
        └────────────┬────────────────────────┬────────────────────┘
                     │                        │
                     ▼                        ▼
            ┌────────────────┐        ┌──────────────────┐
            │ Zabbix API     │        │  SMTP (Gmail)    │
            │ (JSON-RPC)     │        │                  │
            └────────────────┘        └──────────────────┘

A request from the AI assistant arrives over MCP stdio, is routed to an async tool handler, which delegates to the service layer (ZabbixClient, email, graph). Every layer pulls its configuration from a single pydantic-settings Settings object and logs through one rotating handler.

---

Highlights

• Fully async — httpx.AsyncClient with bearer-token auth, configurable timeout, and exponential-backoff retries for transient failures.
• Typed boundaries — Pydantic v2 models validate tool inputs (emails, IP addresses, time ranges) before they reach the network.
• Single source of truth for config — pydantic-settings reads from process env then .env; secrets are wrapped in SecretStr.
• Stdio-safe logging — rotating file handler + stderr stream (never pollutes the MCP protocol on stdout).
• Graph rendering — saves a PNG to disk and returns base64 so MCP clients can render inline without a second round-trip.
• Graceful degradation — the email tool is automatically disabled when SMTP credentials are missing, returning a structured error rather than crashing the server.
• Tested — async pytest suite with respx-mocked HTTP, no real Zabbix required for CI.

---

Available tools

Tool	Signature	Description
get_zabbix_host	()	List hosts with interfaces, groups, and tags.
get_zabbix_host_group	()	List host groups.
get_zabbix_host_by_group	(group_id: str)	Hosts within a group.
get_zabbix_item	(host_id: str)	Items configured on a host.
get_zabbix_problem	()	Current problems (most recent first).
get_zabbix_problem_by_host	(host_id: str)	Problems for a single host.
get_zabbix_trend	(item_id, start_time, end_time)	Trend rows for an item.
get_zabbix_user	()	Users with roles and access flags.
get_zabbix_proxy	()	Proxy inventory.
get_zabbix_ha_cluster_nodes	()	HA cluster node state.
create_zabbix_host	(hostname, ip, group_ids, ...)	Create a host (agent/snmp/ipmi/jmx).
send_email_tool	(to_email, subject, body)	Send via SMTP.
construct_graph	(item_id, start_time, end_time, item_name)	Render trend chart (PNG + base64).

All Zabbix tools return the raw result payload from the JSON-RPC response. On failure they return a structured {"error": ..., "type": ...} envelope rather than throwing.

---

Project layout

mcp_zabbix/
├── src/mcp_zabbix/
│   ├── __init__.py
│   ├── main.py              # FastMCP entrypoint + tool registrations
│   ├── core/
│   │   ├── config.py        # pydantic-settings (env + .env)
│   │   ├── logging.py       # rotating file + stderr handlers
│   │   └── exceptions.py    # ZabbixAPIError / EmailError / GraphError
│   ├── models/
│   │   └── zabbix.py        # Pydantic schemas for tool I/O
│   └── services/
│       ├── zabbix.py        # async ZabbixClient (retry, auth)
│       ├── email.py         # SMTP wrapper (asyncio.to_thread)
│       └── graph.py         # matplotlib renderer (PNG + base64)
├── tests/
│   ├── conftest.py          # autouse env stubbing
│   ├── test_config.py
│   ├── test_zabbix_client.py  # respx-mocked HTTP
│   └── test_graph.py
├── Dockerfile               # python:3.12-slim, non-root user
├── docker-compose.yml       # mounts ./logs and ./output
├── pyproject.toml           # hatchling build, dev extras, ruff/mypy
├── requirements.txt         # mirror of runtime deps for pip users
├── run.sh                   # convenience launcher (loads .env)
├── .env.example
└── LICENSE

---

Quick start

Prerequisites

• Python 3.10 or newer
• A reachable Zabbix server with a valid API token
• (Optional) Gmail / SMTP credentials for the email tool

Local (pip)

git clone https://github.com/badoss/mcp_zabbix.git
cd mcp_zabbix

python -m venv .venv
source .venv/bin/activate            # Windows: .venv\Scripts\activate

pip install -e ".[dev]"
cp .env.example .env                 # edit ZABBIX_API_URL / TOKEN
./run.sh                             # or: mcp-zabbix

Local (uv)

uv is a fast Rust-based replacement for pip:

uv sync                              # installs runtime deps
uv sync --extra dev                  # add dev tooling
cp .env.example .env
uv run mcp-zabbix

Docker

cp .env.example .env                 # edit secrets
docker compose up --build

./logs and ./output are mounted into the container so log files and generated PNGs persist on the host.

---

Configuration

All settings come from environment variables. A .env file in the project root is loaded automatically. Full list (see .env.example):

Zabbix

Variable	Default	Description
ZABBIX_API_URL	— (required)	Full URL to api_jsonrpc.php.
ZABBIX_API_TOKEN	— (required)	Bearer token (stored as SecretStr).
ZABBIX_REQUEST_TIMEOUT	30	HTTP timeout in seconds.
ZABBIX_MAX_RETRIES	3	Transient-failure retry budget.

SMTP (optional)

Variable	Default	Description
SMTP_HOST	smtp.gmail.com	SMTP server host.
SMTP_PORT	587	SMTP server port (STARTTLS).
SMTP_USER	empty	Login user; required to enable email.
SMTP_PASSWORD	empty	Login password or Gmail app password.
SMTP_FROM_NAME	MCP Zabbix	Display name in the From header.

Gmail note: enable 2FA and create an app password — regular account passwords are no longer accepted by Google's SMTP.

Runtime

Variable	Default	Description
LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR / CRITICAL.
LOG_DIR	logs	Rotating log directory (5 MB × 3 backups).
GRAPH_OUTPUT_DIR	output	Where trend PNGs are written.

---

MCP client setup

Claude Desktop / Cursor (uv launcher)

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mcp-zabbix": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp_zabbix",
        "mcp-zabbix"
      ]
    }
  }
}

pip-installed virtualenv

{
  "mcpServers": {
    "mcp-zabbix": {
      "command": "/absolute/path/to/mcp_zabbix/.venv/bin/mcp-zabbix"
    }
  }
}

Docker

{
  "mcpServers": {
    "mcp-zabbix": {
      "command": "docker",
      "args": ["compose", "-f", "/absolute/path/to/docker-compose.yml", "run", "--rm", "mcp-zabbix"]
    }
  }
}

Restart your MCP client after editing the config — the tools should then show up in its tool palette.

---

Usage examples

Once connected, prompt your assistant in plain language; it will pick the right tool automatically.

List monitored hosts

Show me every Zabbix host along with its group memberships.

Investigate problems on a host

What active problems does host 10084 have? Group them by severity.

Render a trend chart

Plot the last 24 hours of CPU utilization for item 50134 and call the chart "Web-01 CPU".

The construct_graph tool returns the on-disk path plus a base64-encoded PNG — most MCP clients will render the chart inline.

Send an alert email

Email [email protected] with subject "P1: DB latency" and a one-line body describing the current problem.

The email tool returns {"status": "sent", ...} on success, or a structured error envelope if SMTP isn't configured.

---

Development

pip install -e ".[dev]"

# run the test suite (async + respx-mocked HTTP)
pytest

# lint & format
ruff check src tests
ruff format src tests

# strict type-check
mypy src

The test suite uses pytest-asyncio (auto mode) and respx to mock httpx. No real Zabbix server is required for CI.

To run the server against your local Zabbix:

cp .env.example .env
$EDITOR .env
./run.sh

---

License

Released under the MIT License.

Support

• Bug reports & feature requests: GitHub Issues
• Zabbix API reference: https://www.zabbix.com/documentation/current/en/manual/api
• MCP specification: https://modelcontextprotocol.io