Zabbix MCP Server

🚀 Zabbix MCP Server

Zabbix MCP Server 是一个全面的模型上下文协议（MCP）服务器，它借助 FastMCP 和 python - zabbix - utils 实现与 Zabbix 的集成。该服务器通过支持 MCP 的工具，提供对 Zabbix API 功能的完整访问。

🚀 快速开始

前提条件

• Python 3.10 或更高版本
• uv 包管理器
• 可访问启用了 API 的 Zabbix 服务器

快速上手

1. 克隆仓库：

   git clone https://github.com/mpeirone/zabbix-mcp-server.git
   cd zabbix-mcp-server
   

2. 安装依赖：

   uv sync
   

3. 配置环境变量：

   cp config/.env.example .env
   # 用你的 Zabbix 服务器详细信息编辑 .env
   

4. 测试安装：

   uv run python scripts/test_server.py
   

✨ 主要特性

🏠 主机管理

• host_get - 通过高级过滤检索主机
• host_create - 创建带有接口和模板的新主机
• host_update - 更新现有主机配置
• host_delete - 从监控中移除主机

👥 主机组管理

• hostgroup_get - 检索主机组
• hostgroup_create - 创建新的主机组
• hostgroup_update - 修改现有主机组
• hostgroup_delete - 移除主机组

📊 监控项管理

• item_get - 通过过滤检索监控项
• item_create - 创建新的监控项
• item_update - 更新现有监控项
• item_delete - 移除监控项

⚠️ 触发器管理

• trigger_get - 检索触发器和警报
• trigger_create - 创建新的触发器
• trigger_update - 修改现有触发器
• trigger_delete - 移除触发器

📋 模板管理

• template_get - 检索监控模板
• template_create - 创建新模板
• template_update - 更新现有模板
• template_delete - 移除模板

🚨 问题与事件管理

• problem_get - 检索当前问题和故障
• event_get - 获取历史事件
• event_acknowledge - 确认事件和问题

📈 数据检索

• history_get - 访问历史监控数据
• trend_get - 检索趋势数据和统计信息

👤 用户管理

• user_get - 检索用户账户
• user_create - 创建新用户
• user_update - 更新用户信息
• user_delete - 移除用户账户

🔧 维护管理

• maintenance_get - 检索维护周期
• maintenance_create - 安排维护窗口
• maintenance_update - 修改维护周期
• maintenance_delete - 移除维护计划

📊 附加特性

• graph_get - 检索图形配置
• discoveryrule_get - 获取发现规则
• itemprototype_get - 检索监控项原型
• configuration_export - 导出 Zabbix 配置
• configuration_import - 导入配置
• apiinfo_version - 获取 API 版本信息

📦 安装指南

前提条件

• Python 3.10 或更高版本
• uv 包管理器
• 可访问启用了 API 的 Zabbix 服务器

安装步骤

1. 克隆仓库：

   git clone https://github.com/mpeirone/zabbix-mcp-server.git
   cd zabbix-mcp-server
   

2. 安装依赖：

   uv sync
   

3. 配置环境变量：

   cp config/.env.example .env
   # 用你的 Zabbix 服务器详细信息编辑 .env
   

4. 测试安装：

   uv run python scripts/test_server.py
   

💻 使用示例

基础用法

# 获取所有主机
host_get()

# 获取特定组中的主机
host_get(groupids=["1"])

高级用法

# 创建一个新主机
host_create(
    host="server-01",
    groups=[{"groupid": "1"}],
    interfaces=[{
        "type": 1,
        "main": 1,
        "useip": 1,
        "ip": "192.168.1.100",
        "dns": "",
        "port": "10050"
    }]
)

# 获取最近的问题
problem_get(recent=True, limit=10)

# 获取历史数据
history_get(
    itemids=["12345"],
    time_from=1640995200,
    limit=100
)

📚 详细文档

配置

必需的环境变量

• ZABBIX_URL - 你的 Zabbix 服务器 API 端点（例如，https://zabbix.example.com）

认证（选择一种方法）

方法 1：API 令牌（推荐）

• ZABBIX_TOKEN - 你的 Zabbix API 令牌

方法 2：用户名/密码

• ZABBIX_USER - 你的 Zabbix 用户名
• ZABBIX_PASSWORD - 你的 Zabbix 密码

可选配置

• READ_ONLY - 设置为 true、1 或 yes 以启用只读模式（仅允许 GET 操作）

运行服务器

使用启动脚本（推荐）：

uv run python scripts/start_server.py

直接执行：

uv run python src/zabbix_mcp_server.py

测试

运行测试套件：

uv run python scripts/test_server.py

只读模式

当 READ_ONLY=true 时，服务器将仅公开 GET 操作（检索数据），并阻止所有创建、更新和删除操作。这适用于以下场景：

• 📊 监控仪表盘
• 🔍 只读集成
• 🔒 注重安全的环境
• 🛡️ 防止意外修改

MCP 集成

此服务器设计用于与如 Claude Desktop 等支持 MCP 的客户端配合使用。有关详细的集成说明，请参阅 MCP_SETUP.md。

Docker 支持

使用 Docker Compose

1. 配置环境：

   cp config/.env.example .env
   # 用你的设置编辑 .env
   

2. 使用 Docker Compose 运行：

   docker compose up -d
   

构建 Docker 镜像

docker build -t zabbix-mcp-server .

开发

项目结构

zabbix-mcp-server/
├── src/
│   └── zabbix_mcp_server.py    # 主服务器实现
├── scripts/
│   ├── start_server.py         # 带有验证的启动脚本
│   └── test_server.py          # 测试脚本
├── config/
│   ├── .env.example           # 环境配置模板
│   └── mcp.json               # MCP 客户端配置示例
├── pyproject.toml             # Python 项目配置
├── requirements.txt           # 依赖项
├── Dockerfile                 # Docker 配置
├── docker-compose.yml         # Docker Compose 设置
├── README.md                  # 本文件
├── MCP_SETUP.md              # MCP 集成指南
├── CONTRIBUTING.md           # 贡献指南
├── CHANGELOG.md              # 版本历史
└── LICENSE                   # MIT 许可证

贡献代码

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

运行测试

# 测试服务器功能
uv run python scripts/test_server.py

# 使用 Docker 进行测试
docker-compose exec zabbix-mcp python scripts/test_server.py

🔧 技术细节

错误处理

服务器包含全面的错误处理：

• ✅ 明确报告认证错误
• 🔒 以描述性消息阻止只读模式违规
• ✔️ 验证无效参数
• 🌐 正确格式化网络和 API 错误
• 📝 详细记录日志以进行故障排除

安全考虑

• 🔑 尽可能使用 API 令牌而非用户名/密码
• 🔒 为仅用于监控的用例启用只读模式
• 🛡️ 保护好你的环境变量
• 🔐 使用 HTTPS 进行 Zabbix 服务器连接
• 🔄 定期轮换 API 令牌
• 📁 安全存储配置文件

故障排除

常见问题

连接失败：

• 验证 ZABBIX_URL 是否正确且可访问
• 检查认证凭据
• 确保 Zabbix API 已启用

权限被拒：

• 验证用户是否具有足够的 Zabbix 权限
• 检查在尝试修改数据时是否启用了只读模式

工具未找到：

• 确保所有依赖项已安装：uv sync
• 验证 Python 版本兼容性（3.10+）

调试模式

设置环境变量以进行详细日志记录：

export DEBUG=1
uv run python scripts/start_server.py

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

致谢

• Zabbix 提供监控平台
• Model Context Protocol 提供集成标准
• FastMCP 提供服务器框架

支持

• 📖 文档
• 🐛 问题跟踪器
• 💬 讨论区

为 Zabbix 和 MCP 社区用心打造 ❤️