Zabbix-MCP 工具全面介绍

项目地址：Zabbix-MCP

Zabbix-MCP（Zabbix 只读查询中台）是一套面向 Zabbix 监控系统的「查询能力增强层」，通过 REST/CLI 双接口形态，解决 Zabbix 原生接口的使用痛点，提供自然语言查询、日志关联分析等高效能力，同时以「全程只读」为核心原则，为运维与平台团队打造安全、易用的观测分析工具。

一、工具核心定位：为什么需要 Zabbix-MCP？

在 Zabbix 日常使用中，运维团队常面临「接口难用、权限混乱、分析低效」三大问题：原生 API 偏底层，查询条件需手动拼装；接口缺乏细粒度权限控制，易泄露写操作风险；告警与日志数据孤立，故障排查需跨工具联动。Zabbix-MCP 正是为解决这些问题而生。

1.1 核心身份与价值

• 统一查询入口：整合 Zabbix 告警、事件等核心数据，提供标准化查询模型，无需再记忆复杂的原生 API 格式

• 安全只读保障：全局拦截写操作，仅开放查询能力，配合 RBAC 权限体系，彻底规避误操作风险

• 效率提升工具：支持自然语言解析、日志关键词关联等智能能力，将故障排查时间从「小时级」压缩至「分钟级」

1.2 目标用户

运维工程师、SRE 值班人员、平台建设团队、数据分析人员及所有需要使用 Zabbix 数据进行观测与分析的角色。

二、核心功能特性：能帮你解决什么问题？

Zabbix-MCP 以「查询能力」为核心，围绕「安全、高效、可观测」三大维度设计功能，覆盖从日常值班到故障复盘的全场景需求。

2.1 高效查询能力：多形态、多维度的数据分析

（1）双接口形态，适配不同场景

• REST 接口：供平台系统、脚本调用，支持标准化集成
  今日告警查询：GET /alerts/today，支持 limit 控制返回数量

• Top 告警排序：GET /alerts/top，按严重度、频次、时间灵活排序

• 组合条件查询：POST /alerts/query，支持多维度筛选与时间范围解析

CLI 命令行：适合运维人员日常快速操作，支持表格化输出
基础命令：zabbix-mcp today | top | query | associate

优势：无需拼接 HTTP 请求，通过命令参数即可完成复杂查询，结果经 Rich 库美化展示

（2）智能查询增强，降低使用门槛

• 自然语言解析：通过 POST /alerts/nl 接口，直接输入「今日告警 top5 按严重度排序」等中文文本，自动转换为结构化查询条件，非技术人员也能轻松使用

• 日志关键词关联：通过 POST /logs/associate 接口，输入故障关键词（如「Processor load」），即可匹配相关告警事件，实现日志与告警的联动分析

2.2 安全与权限：细粒度控制，操作可追溯

• RBAC 权限体系：通过两种令牌区分权限——MCP_AUTH_TOKEN_READ（只读权限，用于日常查询）和 MCP_AUTH_TOKEN_ADMIN（管理员权限，用于配置管理），避免权限滥用

• 全链路审计：内置审计中间件，自动记录所有请求的路由、操作方法、用户角色、执行状态及耗时，支持故障追溯与合规检查

• 只读安全防线：通过 READ_ONLY=1 全局配置开启只读模式，自动拦截所有写类操作，确保 Zabbix 核心数据安全

2.3 可观测性支撑：自身状态全掌控

• Prometheus 指标暴露：通过 /metrics 接口输出请求计数、时延直方图等核心指标，可直接接入 Prometheus 实现监控告警，支撑容量规划与性能优化

• 轻量任务队列：内置任务队列机制，可处理离线查询、批量分析等耗时操作，避免长请求阻塞服务

• WebSocket 状态监控：通过 /mcp/ws 接口实现客户端注册与心跳回显，实时监控服务连接状态

三、技术架构：可靠与高效的保障

Zabbix-MCP 采用轻量级架构设计，兼顾性能与易用性，支持 Windows、Linux 多环境部署，可快速融入现有运维体系。

3.1 系统架构图

架构说明：用户通过 CLI 或 HTTP 客户端发起请求，MCP 服务作为中间层，通过 Zabbix JSON-RPC 接口获取数据并进行聚合处理，同时对外提供指标监控与状态反馈能力，全程不修改 Zabbix 核心数据。

3.2 核心技术栈

技术组件	核心作用
FastAPI	高性能异步 Web 框架，支持声明式路由与依赖注入，提升接口响应速度
httpx	异步 HTTP 客户端，配合信号量实现并发控制与限流，避免压垮 Zabbix 服务
Pydantic v2	数据模型校验，确保输入参数规范，防止恶意请求
Typer + Rich	构建友好的 CLI 交互，支持表格化输出与色彩高亮
Prometheus Client	内置指标采集，支撑服务自身可观测性

3.3 关键技术亮点

• 统一 RPC 调用封装：对 Zabbix JSON-RPC 接口进行二次封装，内置鉴权、错误处理与并发控制，提升调用可靠性

• 智能数据聚合：服务层自动完成事件与触发器数据的关联，补充严重级别、告警描述等信息，无需用户手动关联查询

• 严格输入校验：所有用户输入经 Pydantic 二次校验，错误信息携带标准化提示，降低问题定位成本

• 多环境适配：基于 Uvicorn ASGI 运行，支持 Windows、Linux 系统，部署方式灵活

四、快速上手：3 步开启使用

Zabbix-MCP 部署简单，配置灵活，无需修改 Zabbix 原有配置，即可快速接入。

4.1 环境准备

依赖 Python 3.8+ 环境，支持虚拟环境隔离，避免依赖冲突。

4.2 安装部署

（1）Windows 环境（PowerShell）

# 1. 进入项目根目录
cd e:\Zabbix-MCP
# 2. 执行启动脚本（自动创建虚拟环境、安装依赖并启动服务）
./scripts/start_win38.ps1 -EnvFile .env -Port 5656 -Host 0.0.0.0

（2）Linux/macOS 环境

# 1. 进入项目根目录
cd /path/to/Zabbix-MCP
# 2. 创建并激活虚拟环境
python3 -m venv .venv && source .venv/bin/activate
# 3. 安装依赖与服务
python -m pip install -U pip
python -m pip install -e .
# 4. 启动服务
uvicorn zabbix_mcp.api:app --host 0.0.0.0 --port 5656

4.3 核心配置（.env 文件）

需配置 Zabbix 连接信息与权限令牌，核心配置项如下（必填项标*）：

• Zabbix 连接信息*：ZABBIX_URL（Zabbix 服务地址）、ZABBIX_USERNAME/ZABBIX_PASSWORD 或 ZABBIX_TOKEN（鉴权凭证）

• 权限令牌*：MCP_AUTH_TOKEN_READ（只读令牌）、MCP_AUTH_TOKEN_ADMIN（管理员令牌）

• 性能控制：MAX_CONCURRENCY（最大并发数）、MAX_RESULTS_LIMIT（查询结果上限）

• 安全配置：READ_ONLY=1（开启只读模式，生产环境建议强制开启）

4.4 快速使用示例

（1）REST 接口查询（今日 Top5 告警）

curl -H "Authorization: Bearer 你的只读令牌" "http://localhost:5656/alerts/today?limit=5"

（2）CLI 命令查询（按严重度排序 Top5 告警）

zabbix-mcp top --by severity --limit 5 --token 你的只读令牌

（3）自然语言查询（中文）

curl -H "Authorization: Bearer 你的只读令牌" -H "Content-Type: application/json" \
  -d '{"text":"今日告警 top5 按严重度排序"}' http://localhost:5656/alerts/nl

五、项目发展与支持

5.1 当前版本与更新

当前稳定版本：0.1.0（初始发布版），已包含 REST/CLI 双接口、自然语言解析、日志关联、RBAC 权限等核心功能。

5.2 未来规划（坚持只读原则）

• 短期：增强自然语言解析的语义识别能力，支持更多时间表达式（如「近1小时」「昨天」）

• 中期：实现多 Zabbix 实例路由，支持同时查询多个 Zabbix 服务的数据

• 长期：开发可视化指标面板，提供告警趋势分析与阈值建议功能

5.3 贡献与支持

• 贡献流程：Fork 仓库 → 新建功能分支 → 完成开发 → 运行冒烟测试 → 提交 PR

• 冒烟测试：执行 scripts/smoke_test.ps1（Windows）或 scripts/smoke_test.sh（Linux）验证核心功能可用性

• 问题反馈：通过 GitHub 仓库 Issue 提交需求或问题，建议附带调用示例与日志信息

六、附录：相关资源

• 项目完整文档：../README.md（可通过项目 GitHub 仓库获取）

• 接口详细说明：./API.md（可通过项目 GitHub 仓库获取）

• Zabbix API 官方文档：https://www.zabbix.com/documentation/current/en/manual/api

• 核心依赖文档：FastAPI（https://fastapi.tiangolo.com/）、Prometheus Client（https://github.com/prometheus/client_python）