Mcp Zabbix

MCP Zabbix

一个面向生产环境的 Model Context Protocol 服务，可将 Zabbix 监控 API 接入 Claude Desktop、Cursor 等 AI 助手，以及任何其他兼容 MCP 的客户端。该服务基于 FastMCP 构建，使用异步 httpx 客户端、类型化的 Pydantic 模型、结构化日志记录，以及趋势图渲染器；渲染器会返回磁盘上的 PNG 文件和用于内嵌显示的 base64 载荷。

---

目录

• 架构
• 亮点
• 可用工具
• 项目布局
• 快速开始
  • 本地（pip）
  • 本地（uv）
  • Docker
• 配置
• MCP 客户端设置
• 使用示例
• 开发
• 许可证

---

架构

                       ┌─────────────────────────────────────┐
                       │       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)     │        │                  │
            └────────────────┘        └──────────────────┘

来自 AI 助手的请求通过 MCP stdio 到达，并路由至异步工具处理程序；处理程序再委托给服务层（ZabbixClient、电子邮件、图表）。每一层都从同一个 pydantic-settings Settings 对象读取配置，并通过一个轮转处理程序记录日志。

---

亮点

• 完全异步 — 使用 httpx.AsyncClient 和 bearer 令牌身份验证，支持可配置的超时时间，并针对瞬时故障进行指数退避重试。
• 类型化边界 — Pydantic v2 模型会在工具输入（电子邮件、IP 地址、时间范围）到达网络之前进行验证。
• 配置的单一事实来源 — pydantic-settings 先读取进程环境变量，再读取 .env；机密使用 SecretStr 封装。
• 适用于 stdio 的日志记录 — 轮转文件处理程序 + stderr 流（绝不会污染 stdout 上的 MCP 协议）。
• 图表渲染 — 将 PNG 保存到磁盘，并且返回 base64，使 MCP 客户端无需再次往返即可内嵌渲染。
• 优雅降级 — 缺少 SMTP 凭据时会自动禁用电子邮件工具，并返回结构化错误，而不是导致服务崩溃。
• 经过测试 — 使用 respx 模拟 HTTP 的异步 pytest 测试套件；CI 无需连接真实的 Zabbix。

---

可用工具

工具	签名	描述
get_zabbix_host	()	列出包含接口、组和标签的主机。
get_zabbix_host_group	()	列出主机组。
get_zabbix_host_by_group	(group_id: str)	列出某个组中的主机。
get_zabbix_item	(host_id: str)	列出主机上配置的监控项。
get_zabbix_problem	()	列出当前问题（按最新时间优先）。
get_zabbix_problem_by_host	(host_id: str)	列出单台主机的问题。
get_zabbix_trend	(item_id, start_time, end_time)	获取某个监控项的趋势数据行。
get_zabbix_user	()	列出包含角色和访问标志的用户。
get_zabbix_proxy	()	列出代理清单。
get_zabbix_ha_cluster_nodes	()	获取 HA 集群节点状态。
create_zabbix_host	(hostname, ip, group_ids, ...)	创建主机（agent/snmp/ipmi/jmx）。
send_email_tool	(to_email, subject, body)	通过 SMTP 发送邮件。
construct_graph	(item_id, start_time, end_time, item_name)	渲染趋势图表（PNG + base64）。

所有 Zabbix 工具都会返回 JSON-RPC 响应中的原始 result 载荷。 发生故障时，它们会返回结构化的 {"error": ..., "type": ...} 信封，而不是抛出异常。

---

项目布局

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

---

快速开始

前置条件

• Python 3.10 或更高版本
• 可访问且具有有效 API 令牌的 Zabbix 服务器
• （可选）用于邮件工具的 Gmail / SMTP 凭据

本地安装（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

本地安装（uv）

uv 是一款基于 Rust 的快速 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 和 ./output 会挂载到容器中，以便日志文件和 生成的 PNG 文件保留在主机上。

---

配置

所有设置均通过环境变量提供。项目 根目录中的 .env 文件会自动加载。完整列表请参见 .env.example：

Zabbix

变量	默认值	描述
ZABBIX_API_URL	— （必需）	api_jsonrpc.php 的完整 URL。
ZABBIX_API_TOKEN	— （必需）	Bearer 令牌（以 SecretStr 存储）。
ZABBIX_REQUEST_TIMEOUT	30	HTTP 超时时间，单位为秒。
ZABBIX_MAX_RETRIES	3	针对暂时性故障的重试次数上限。

SMTP（可选）

变量	默认值	描述
SMTP_HOST	smtp.gmail.com	SMTP 服务器主机。
SMTP_PORT	587	SMTP 服务器端口（STARTTLS）。
SMTP_USER	空	登录用户名；启用邮件功能时必需。
SMTP_PASSWORD	空	登录密码或 Gmail 应用专用密码。
SMTP_FROM_NAME	MCP Zabbix	From 标头中显示的名称。

**Gmail 提示：**启用两步验证并创建应用专用密码 — Google 的 SMTP 不再接受普通账户密码。

运行时

变量	默认值	描述
LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR / CRITICAL。
LOG_DIR	logs	轮换日志目录（5 MB × 3 backups）。
GRAPH_OUTPUT_DIR	output	趋势 PNG 文件的写入位置。

---

MCP 客户端配置

Claude Desktop / Cursor（uv 启动器）

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

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

通过 pip 安装的虚拟环境

{
  "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"]
    }
  }
}

编辑配置后重启 MCP 客户端 — 工具随后应会显示在其工具面板中。

---

使用示例

连接后，用日常语言向助手发送提示词；它会自动选择合适的工具。

列出受监控的主机

列出所有 Zabbix 主机及其所属的组。

调查某台主机上的问题

主机 10084 有哪些活动问题？按严重性分组。

生成趋势图

绘制项目 50134 过去 24 小时的 CPU 使用率，并将图表命名为 "Web-01 CPU"。

construct_graph 工具会返回磁盘上的文件路径以及 base64 编码的 PNG — 大多数 MCP 客户端会以内嵌方式显示图表。

发送告警邮件

给 [email protected] 发送邮件，主题为 "P1: DB latency"，正文用一句话描述当前问题。

邮件工具成功时会返回 {"status": "sent", ...}，如果未配置 SMTP，则会返回结构化的错误信息。

---

开发

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

测试套件使用 pytest-asyncio（自动模式）和 respx 模拟 httpx。CI 无需真实的 Zabbix 服务器。

要让服务器连接到本地 Zabbix：

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

---

许可证

基于 MIT License 发布。

支持

• Bug 报告和功能请求：GitHub Issues
• Zabbix API 参考：https://www.zabbix.com/documentation/current/en/manual/api
• MCP 规范：https://modelcontextprotocol.io