zbx-mcp by duanshuaimin - MCP Server

Zabbix MCP Server

统一化 Zabbix 监控管理的 MCP 服务器

Zabbix MCP Server 是一个基于 FastMCP 2.0 框架开发的 Model Context Protocol (MCP) 服务器，旨在为 AI 助手提供统一的 Zabbix 监控系统管理接口。通过标准化的 MCP 协议，AI 助手可以轻松地与多个 Zabbix 实例进行交互，实现智能化的监控管理和运维自动化。

✨ 主要特性

🔌 MCP 标准化接口

统一协议: 基于 Model Context Protocol 标准，提供一致的 API 接口
AI 友好: 专为 AI 助手和智能工具设计的交互界面
多实例支持: 同时管理多个 Zabbix 服务器实例

🛠️ 核心功能模块

主机管理 (Host Management)

主机发现和自动注册
主机组织和分类管理
主机配置批量操作
主机状态监控和报告

监控数据查询 (Monitoring Data Query)

实时性能指标查询
历史数据趋势分析
自定义时间范围数据获取
多维度数据聚合和统计

告警和事件管理 (Alert & Event Management)

实时告警事件获取
告警严重级别分类
事件确认和处理跟踪
告警趋势分析和预测

模板和配置管理 (Template & Configuration Management)

监控模板的创建和管理
配置模板批量应用
监控项和触发器配置
配置版本控制和回滚

自动化脚本执行 (Automation & Script Execution)

远程脚本执行和管理
自动化运维任务调度
故障自动修复脚本
操作日志和审计跟踪

数据分析和报告 (Data Analysis & Reporting)

性能数据可视化分析
自定义报告生成
容量规划和预测分析
SLA 监控和合规报告

🔧 技术架构

框架: FastMCP 2.0 - 现代化的 MCP 服务器框架
API 通信: JSON-RPC 协议与 Zabbix API 交互
数据处理: Pandas + NumPy 进行数据分析和处理
可视化: Matplotlib + Plotly 提供图表和可视化支持
缓存: Redis 缓存提升查询性能
安全: JWT 令牌认证和数据加密传输
日志: 结构化日志记录和监控

🚀 快速开始

环境要求

Python: 3.9 或更高版本
Zabbix: 6.0+ (支持 JSON-RPC API)
Redis: 6.0+ (可选，用于缓存)

安装

方式一：使用 pip 安装

pip install zabbix-mcp-server

方式二：从源码安装

# 克隆仓库
git clone https://github.com/yourusername/zabbix-mcp-server.git
cd zabbix-mcp-server

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 安装依赖
pip install -e .

配置

创建配置文件：

cp config/environment.template .env

编辑配置：

# .env 文件示例
ZABBIX_DEFAULT_URL=https://your-zabbix-server.com/api_jsonrpc.php
ZABBIX_DEFAULT_USERNAME=your_username
ZABBIX_DEFAULT_PASSWORD=your_password

MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8080
MCP_SERVER_DEBUG=false

SECRET_KEY=your-secret-key-here

启动服务器

# 启动 MCP 服务器
zabbix-mcp-server serve --host 0.0.0.0 --port 8080

# 或使用配置文件
zabbix-mcp-server serve --config config/production.yaml

基本使用

# Python 客户端示例
import asyncio
from mcp import Client

async def main():
    async with Client("http://localhost:8080") as client:
        # 获取主机列表
        hosts = await client.call_tool("get_hosts", {
            "group": "Linux servers"
        })
        
        # 查询性能数据
        metrics = await client.call_tool("get_metrics", {
            "host": "web-server-01",
            "items": ["cpu.usage", "memory.usage"],
            "period": "1h"
        })
        
        print(f"发现 {len(hosts)} 台主机")
        print(f"获取到 {len(metrics)} 个指标数据点")

if __name__ == "__main__":
    asyncio.run(main())

📚 文档

- 如何设置开发环境
- 完整的 API 文档
- 详细的配置说明
- 生产环境部署
- 如何参与项目贡献

🛡️ 安全性

身份认证: 支持 API 密钥和 JWT 令牌认证
传输加密: HTTPS/TLS 加密通信
访问控制: 基于角色的权限管理
审计日志: 完整的操作审计跟踪

🔄 API 工具

主机管理工具

工具名称	描述	参数
`get_hosts`	获取主机列表	`group`, `status`, `filter`
`create_host`	创建新主机	`name`, `ip`, `groups`, `templates`
`update_host`	更新主机配置	`host_id`, `updates`
`delete_host`	删除主机	`host_id`

监控数据工具

工具名称	描述	参数
`get_metrics`	获取性能指标	`host`, `items`, `period`
`get_trends`	获取趋势数据	`items`, `time_range`
`get_history`	获取历史数据	`item_id`, `start_time`, `end_time`

告警管理工具

工具名称	描述	参数
`get_alerts`	获取告警列表	`severity`, `status`, `time_range`
`acknowledge_alert`	确认告警	`alert_id`, `message`
`get_events`	获取事件历史	`host`, `time_range`

🧪 测试

# 运行所有测试
pytest

# 运行特定测试类别
pytest -m unit          # 单元测试
pytest -m integration   # 集成测试
pytest -m slow          # 慢速测试

# 生成覆盖率报告
pytest --cov=src/zbx_mcp --cov-report=html

🤝 贡献

我们欢迎所有形式的贡献！请查看了解详细信息。

开发流程

Fork 本仓库
创建特性分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
创建 Pull Request

代码风格

我们使用以下工具确保代码质量：

Black: 代码格式化
Ruff: 代码检查和 linting
MyPy: 静态类型检查
pytest: 单元测试和集成测试

📄 许可证

本项目采用 MIT 许可证。详见文件。

🙏 致谢

FastMCP - 优秀的 MCP 框架
Zabbix - 强大的监控解决方案
Model Context Protocol - 标准化的协议规范

📞 支持

文档: https://zabbix-mcp-server.readthedocs.io/
问题报告: GitHub Issues
讨论: GitHub Discussions

Zabbix MCP Server - 让 AI 助手轻松管理您的 Zabbix 监控环境！🚀