JinDaGe - zabbix-mcp-server MCP Details

article

README

🚀 Zabbix MCP Server

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

🚀 快速开始

前提条件

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

快速上手

克隆仓库：

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

安装依赖：
```
uv sync
```

配置环境变量：

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

测试安装：
```
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 服务器

安装步骤

克隆仓库：

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

安装依赖：
```
uv sync
```

配置环境变量：

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

测试安装：
```
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

配置环境：

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

使用 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 许可证

贡献代码

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

运行测试

# 测试服务器功能
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 社区用心打造 ❤️

zabbix-mcp-server

README

🚀 Zabbix MCP Server

🚀 快速开始

前提条件

快速上手

✨ 主要特性

🏠 主机管理

👥 主机组管理

📊 监控项管理

⚠️ 触发器管理

📋 模板管理

🚨 问题与事件管理

📈 数据检索

👤 用户管理

🔧 维护管理

📊 附加特性

📦 安装指南

前提条件

安装步骤

💻 使用示例

基础用法

高级用法

📚 详细文档

配置

必需的环境变量

认证（选择一种方法）

可选配置

运行服务器

测试

只读模式

MCP 集成

Docker 支持

使用 Docker Compose

构建 Docker 镜像

开发

项目结构

贡献代码

运行测试

🔧 技术细节

错误处理

安全考虑

故障排除

常见问题

调试模式

📄 许可证

致谢

支持

Runtime guide

Hosted runtime

Local runtime / other methods