lordraw/zabbix-mcp repository overview

⁠Zabbix MCP Server — Docker Guide

⁠Overview

The MCP server runs as a stdio process: the container reads JSON-RPC 2.0 messages from stdin and writes responses to stdout. No network port is exposed. The MCP client (Claude Desktop, an agent, or any other MCP host) spawns the container and communicates over its standard streams.

┌─────────────────────┐   stdin/stdout   ┌───────────────────────┐
│  MCP Client         │ ◄──────────────► │  zabbix-mcp container │
│  (agent, Claude, …) │   JSON-RPC 2.0   │  python server.py     │
└─────────────────────┘                  └──────────┬────────────┘
                                                     │ HTTPS
                                                     ▼
                                          ┌──────────────────────┐
                                          │  Zabbix API          │
                                          │  (JSON-RPC endpoint) │
                                          └──────────────────────┘

⁠Quick start

⁠1 — Build the image

docker build -t zabbix-mcp:latest .

⁠2 — Prepare credentials

Copy .env.example to .env and fill in your Zabbix connection details. Never commit .env to version control.

cp .env.example .env
$EDITOR .env

Minimum required variables:

ZABBIX_URL=https://zabbix.example.com
ZABBIX_TOKEN=your_api_token_here    # or ZABBIX_USER + ZABBIX_PASSWORD

⁠3 — Smoke-test (interactive stdin)

docker run --rm -i --env-file .env zabbix-mcp:latest

The server starts and waits for JSON-RPC input on stdin. Press Ctrl-C to stop.

⁠Using with an MCP client

⁠Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "zabbix": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/.env",
        "zabbix-mcp:latest"
      ]
    }
  }
}

Restart Claude Desktop after editing the config.

⁠Python agent (agent.py / llm.py)

Override build_mcp_server_params() in llm.py to spawn Docker instead of the local venv:

def build_mcp_server_params() -> StdioServerParameters:
    env_file = os.path.abspath(".env")
    return StdioServerParameters(
        command="docker",
        args=["run", "--rm", "-i", "--env-file", env_file, "zabbix-mcp:latest"],
        env={**os.environ},
    )

Or set the ZABBIX_MCP_USE_DOCKER variable and handle the switch in code.

⁠Environment variables reference

All variables are passed via --env-file or individual -e flags.

† Either ZABBIX_TOKEN or the pair ZABBIX_USER + ZABBIX_PASSWORD is required. If both are present, the token takes priority.

⁠Image details

⁠Files included in the image

/app/server.py   — MCP server (10 tools)
/app/util.py     — Zabbix formatting utilities

agent.py, llm.py and .env are not included — the agent runs on the host and connects to the container over stdio.

⁠Building for a specific platform

# For ARM hosts (e.g. Raspberry Pi, Apple Silicon)
docker build --platform linux/arm64 -t zabbix-mcp:latest .

# Multi-platform manifest (requires buildx)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t yourrepo/zabbix-mcp:latest \
  --push .

⁠Updating the image

# Rebuild after changing server.py or requirements.txt
docker build --no-cache -t zabbix-mcp:latest .

⁠Security notes

• Never bake credentials into the image. Always pass them at runtime via --env-file or -e.
• If your Zabbix instance uses a self-signed certificate, set ZABBIX_VERIFY_SSL=false — or better, mount the CA bundle and set REQUESTS_CA_BUNDLE=/certs/ca.pem.
• Use a read-only API token with the minimum required permissions when possible. The MCP server only needs read access for most tools; write access is required only for create_maintenance and delete_maintenance.