星战科技xingzhan.cloud
返回市场
扎比克斯-MCP服务器

扎比克斯-MCP服务器

作者：mpeirone107 星标更新：2025-10-16
安装使用来源：spider==github.com

项目介绍

Zabbix MCP 服务器

MIT 许可证 Python 3.10+

一个全面的模型上下文协议（MCP）服务器，用于通过 FastMCP 和 python-zabbix-utils 集成 Zabbix。此服务器通过兼容 MCP 的工具提供了对 Zabbix API 功能的完全访问。

<a href="https://glama.ai/mcp/servers/@mpeirone/zabbix-mcp-server"> <img width="380" height="200" src="https://gips3.baidu.com/it/u=3588777768,898081203&fm=3081&app=3081&f=PNG?w=760&h=400" alt="zabbix-mcp-server MCP 服务器" /> </a>

特性

🏠 主机管理

  • 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 - 移除用户账户

🔗 代理管理

  • proxy_get - 使用过滤器检索 Zabbix 代理
  • proxy_create - 创建新的代理
  • proxy_update - 更新现有的代理
  • proxy_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
# 编辑 .env 文件，填写您的 Zabbix 服务器详情

  4. 测试安装：

    uv run python scripts/test_server.py

配置

必要的环境变量

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

认证（选择一种方法）

方法 1：API Token（推荐）

  • ZABBIX_TOKEN - 您的 Zabbix API Token

方法 2：用户名/密码

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

可选配置

  • READ_ONLY - 设置为 true、1 或 yes 启用只读模式（仅允许 GET 操作）
  • VERIFY_SSL - 启用或禁用 SSL 证书验证（默认：true）

传输配置

  • ZABBIX_MCP_TRANSPORT - 传输类型：stdio（默认）或 streamable-http

HTTP 传输配置（仅在 ZABBIX_MCP_TRANSPORT=streamable-http 时使用）：

  • ZABBIX_MCP_HOST - 服务器主机（默认：127.0.0.1）
  • ZABBIX_MCP_PORT - 服务器端口（默认：8000）
  • ZABBIX_MCP_STATELESS_HTTP - 无状态模式（默认：false）
  • AUTH_TYPE - 必须设置为 no-auth 以使用 streamable-http 传输

使用

运行服务器

使用启动脚本（推荐）：

uv run python scripts/start_server.py

直接执行：

uv run python src/zabbix_mcp_server.py

传输选项

服务器支持两种传输方式：

STDIO 传输（默认）

标准输入/输出传输，适用于像 Claude Desktop 这样的 MCP 客户端：

# 在 .env 或环境中设置
ZABBIX_MCP_TRANSPORT=stdio

HTTP 传输

基于 HTTP 的传输，适用于 Web 集成：

# 在 .env 或环境中设置
ZABBIX_MCP_TRANSPORT=streamable-http
ZABBIX_MCP_HOST=127.0.0.1
ZABBIX_MCP_PORT=8000
ZABBIX_MCP_STATELESS_HTTP=false
AUTH_TYPE=no-auth

注意： 当使用 streamable-http 传输时，必须将 AUTH_TYPE 设置为 no-auth。

测试

运行测试套件：

uv run python scripts/test_server.py

只读模式

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

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

示例工具调用

获取所有主机：

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
)

获取所有代理：

proxy_get()

创建新的主动代理：

proxy_create(
    host="proxy-01",
    status=5,
    description="主要数据中心代理"
)

MCP 集成

此服务器旨在与兼容 MCP 的客户端（如 Claude Desktop）一起工作。请参阅 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 '添加惊人的功能')
  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 Token 而不是用户名/密码
  • 🔒 对于仅用于监控的情况，启用只读模式
  • 🛡️ 保护您的环境变量
  • 🔐 使用 HTTPS 连接到 Zabbix 服务器
  • 🔄 定期轮换 API Token
  • 📁 安全存储配置文件

故障排除

常见问题

连接失败：

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

权限被拒绝：

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

未找到工具：

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

调试模式

设置环境变量以启用详细日志记录：

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

依赖项

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

支持

为 Zabbix 和 MCP 社区制作 ❤️