Zabbix MCP

🚀 Zabbix MCP Server

Zabbix MCP Server是一个基于Python的模型上下文协议（MCP）服务器，旨在为Zabbix监控数据和管理功能提供高级的可编程访问。它提供了一个现代化的API，用于查询、自动化和集成Zabbix资源，如主机、模板、触发器、监控项、问题、事件、用户、代理、维护周期等。该服务器支持读写操作，具备强大的安全特性，适合与AI助手、自动化工具、仪表盘和自定义监控工作流集成。

🚀 快速开始

Zabbix MCP Server为用户提供了便捷的方式来访问和管理Zabbix监控系统的数据和功能。以下是开始使用该服务器的基本步骤和相关信息。

✨ 主要特性

核心特性

• 可灵活过滤查询Zabbix的主机、模板、监控项、触发器和主机组。
• 可按严重程度过滤检索问题、事件和警报。
• 访问监控项的历史和趋势数据。
• 监控触发器状态和问题严重程度。
• 管理维护周期和计划停机时间。
• 检索用户宏和配置数据。
• 获取SLA和服务信息。

管理操作

• 创建、更新和删除主机、模板和主机组（如果启用）。
• 管理触发器、监控项和发现规则。
• 配置维护周期和用户宏。
• 在监控主机上执行脚本。
• 确认事件并关闭问题。
• 创建和管理用户及代理。
• 支持对主机和模板进行批量操作。

高级功能

• 速率限制和API安全功能。
• 只读模式，限制所有写操作以确保安全监控。
• HTTP传输的Bearer令牌认证。
• 全面的日志记录和审计跟踪。
• 支持SSL/TLS和可配置的超时设置。
• 多种传输选项（STDIO、SSE、HTTP）。
• 可选的Sentry集成，用于错误跟踪。

📦 安装指南

前提条件

• Python 3.11 至 3.14
• 访问Zabbix服务器（5.4+）
• 有效的Zabbix API令牌或具有适当权限的用户凭证

从PyPI快速安装

最简单的开始方式是从PyPI安装：

# 使用UV（推荐）
uvx zabbix-mcp

# 或者使用pip
pip install zabbix-mcp

在运行服务器之前，请记得为你的Zabbix实例配置环境变量：

# 创建环境配置
export ZABBIX_URL=https://zabbix.example.com/api_jsonrpc.php
export ZABBIX_TOKEN=your-zabbix-api-token

从源代码安装

1. 克隆仓库：

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

2. 安装依赖：

# 使用UV（推荐）
uv sync

# 或者使用pip
pip install -e .

3. 配置环境变量：

cp .env.example .env
# 用你的Zabbix URL和凭证编辑.env

4. 运行服务器：

# 使用UV
uv run python run_server.py

# 或者直接使用Python
python run_server.py

# 或者使用已安装的脚本
zabbix-mcp

使用Docker

GitHub Packages上提供了Docker镜像，便于部署。

# 普通STDIO镜像
docker pull ghcr.io/mhajder/zabbix-mcp:latest

# 用于Open WebUI的MCPO镜像
docker pull ghcr.io/mhajder/zabbix-mcpo:latest

开发环境设置

若要使用额外工具进行开发：

# 克隆并安装开发依赖
git clone https://github.com/mhajder/zabbix-mcp.git
cd zabbix-mcp
uv sync --group dev

# 运行测试
uv run pytest

# 运行覆盖率测试
uv run pytest --cov=src/

# 运行代码检查和格式化
uv run ruff check .
uv run ruff format .

# 设置预提交钩子
uv run pre-commit install

📚 详细文档

配置

环境变量

# Zabbix连接详情
ZABBIX_URL=https://zabbix.example.com/api_jsonrpc.php

# 认证 - 使用令牌或用户名/密码
# API令牌（Zabbix 5.4+首选）
ZABBIX_TOKEN=your-api-token
# 或者 用户名/密码（适用于旧版本）
# ZABBIX_USER=Admin
# ZABBIX_PASSWORD=zabbix

# SSL配置
ZABBIX_VERIFY_SSL=true
ZABBIX_TIMEOUT=30
ZABBIX_SKIP_VERSION_CHECK=false

# 只读模式
# 将READ_ONLY_MODE设置为true以禁用所有写操作（创建、更新、删除）
READ_ONLY_MODE=false

# 禁用标签
# 以逗号分隔的标签列表，用于禁用工具（默认为空）
# 示例：DISABLED_TAGS=host,user,maintenance
DISABLED_TAGS=

# 日志配置
LOG_LEVEL=INFO

# 速率限制
# 将RATE_LIMIT_ENABLED设置为true以启用速率限制
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=60
RATE_LIMIT_WINDOW_MINUTES=1

# Sentry错误跟踪（可选）
# 设置SENTRY_DSN以启用错误跟踪和性能监控
# SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789
# 可选的Sentry配置
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=true
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP传输配置
# 传输类型：'stdio'（默认）、'sse'（服务器发送事件）或'http'（HTTP可流式传输）
MCP_TRANSPORT=stdio

# HTTP传输设置（当MCP_TRANSPORT=sse或MCP_TRANSPORT=http时使用）
# 绑定HTTP服务器的主机（默认：0.0.0.0表示所有接口）
MCP_HTTP_HOST=0.0.0.0
# 绑定HTTP服务器的端口（默认：8000）
MCP_HTTP_PORT=8000
# 可选的Bearer令牌用于认证（留空表示无认证）
MCP_HTTP_BEARER_TOKEN=

可用工具

API信息

• api_version：获取Zabbix API版本信息

主机管理

• host_get：根据组、模板、代理和搜索条件等进行可选过滤，列出主机。
• host_create：创建带有接口和模板链接的新主机。
• host_update：更新主机属性（名称、状态、描述）。
• host_delete：按ID删除主机。

主机组管理

• hostgroup_get：进行可选过滤，列出主机组。
• hostgroup_create：创建新的主机组。
• hostgroup_update：更新现有主机组的属性（名称）。
• hostgroup_delete：删除主机组。

模板管理

• template_get：进行可选过滤，列出模板。
• template_create：创建新模板。
• template_update：更新模板属性（名称、描述）。
• template_delete：删除模板。

监控项管理

• item_get：根据主机、组、模板进行可选过滤，列出监控项。
• item_create：在主机上创建新的监控项。
• item_update：更新监控项属性（名称、延迟、单位、描述、状态）。
• item_delete：删除监控项。

触发器管理

• trigger_get：按严重程度和状态过滤，列出触发器。
• trigger_create：使用表达式创建新的触发器。
• trigger_update：更新触发器属性（描述、表达式、优先级、状态、注释）。
• trigger_delete：删除触发器。

问题与事件管理

• problem_get：按严重程度和时间过滤，获取当前问题。
• event_get：按时间范围过滤，获取事件。
• event_acknowledge：确认事件并可附带可选消息。

历史与趋势

• history_get：获取监控项的历史数据。
• trend_get：获取监控项的趋势数据。

用户管理

• user_get：进行可选过滤，列出用户。
• user_create：创建新用户。
• user_update：更新用户属性（姓名、姓氏、密码、类型）。
• user_delete：删除用户。

代理管理

• proxy_get：进行可选过滤，列出代理。
• proxy_create：创建新代理。
• proxy_update：更新代理属性（名称、操作模式、描述）。
• proxy_delete：删除代理。

维护管理

• maintenance_get：列出维护周期。
• maintenance_create：创建新的维护周期。
• maintenance_update：更新维护周期属性（名称、时间、描述）。
• maintenance_delete：删除维护周期。

动作与媒体

• action_get：列出动作（触发器、自动注册等）。
• mediatype_get：列出媒体类型。

图形与发现

• graph_get：进行可选过滤，列出图形。
• discoveryrule_get：列出LLD发现规则。
• drule_get：列出网络发现规则。
• itemprototype_get：从发现规则中获取监控项原型。

SLA与服务

• sla_get：列出SLA。
• service_get：列出服务。

脚本

• script_get：列出脚本。
• script_execute：在主机上执行脚本。

用户宏

• usermacro_get：列出用户宏（主机和全局）。
• usermacro_create：创建主机宏。
• usermacro_delete：删除主机宏。

配置管理

• configuration_export：将Zabbix配置导出为JSON或XML。
• configuration_import：从JSON或XML导入Zabbix配置。

安全与安全特性

只读模式

服务器支持只读模式，该模式会禁用所有写操作，以确保安全监控：

READ_ONLY_MODE=true

基于标签的工具过滤

你可以通过设置禁用标签来禁用特定类别的工具：

DISABLED_TAGS=alert,bills

速率限制

服务器支持速率限制，以控制API使用并防止滥用。如果启用，将使用滑动窗口算法对每个客户端的请求进行限制。 在你的.env文件中设置以下环境变量来启用速率限制：

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100   # 每个窗口允许的最大请求数
RATE_LIMIT_WINDOW_MINUTES=1   # 窗口大小（分钟）

如果RATE_LIMIT_ENABLED设置为true，服务器将应用速率限制中间件。根据你的环境需要调整RATE_LIMIT_MAX_REQUESTS和RATE_LIMIT_WINDOW_MINUTES。

Sentry错误跟踪与监控（可选）

服务器可选支持Sentry进行错误跟踪、性能监控和调试。Sentry集成是完全可选的，只有在配置后才会初始化。

安装

要启用Sentry监控，安装可选依赖：

# 使用UV（推荐）
uv sync --extra sentry

配置

通过在你的.env文件中设置SENTRY_DSN环境变量来启用Sentry：

# 必需：你的项目的Sentry DSN
SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789

# 可选：性能监控采样率（0.0 - 1.0，默认：1.0）
SENTRY_TRACES_SAMPLE_RATE=1.0

# 可选：包含个人身份信息（默认：true）
SENTRY_SEND_DEFAULT_PII=true

# 可选：环境名称（例如，"production"、"staging"）
SENTRY_ENVIRONMENT=production

# 可选：发布版本（如果未设置，将从包中自动检测）
SENTRY_RELEASE=1.2.3

# 可选：分析 - 连续分析采样率（0.0 - 1.0，默认：1.0）
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

# 可选：分析 - 分析生命周期模式（默认："trace"）
# 选项："all"、"continuation"、"trace"
SENTRY_PROFILE_LIFECYCLE=trace

# 可选：启用日志捕获作为面包屑和事件（默认：true）
SENTRY_ENABLE_LOGS=true

特性

启用后，Sentry会自动捕获：

• 异常与错误：所有未处理的异常及完整上下文。
• 性能指标：请求/响应时间和跟踪信息。
• MCP集成：详细的MCP服务器活动和交互信息。
• 日志与面包屑：应用程序日志和事件跟踪，用于调试。
• 上下文数据：环境、客户端信息和请求参数。

获取Sentry DSN

1. 在sentry.io创建一个免费账户。
2. 创建一个新的Python项目。
3. 从项目设置中复制你的DSN。
4. 在你的.env文件中设置它。

禁用Sentry

Sentry是完全可选的。如果你不设置SENTRY_DSN，服务器将正常运行，不会有任何Sentry集成，也不会收集监控数据。

SSL/TLS配置

服务器支持SSL证书验证和自定义超时设置：

ZABBIX_VERIFY_SSL=true    # 启用SSL证书验证
ZABBIX_TIMEOUT=30         # 连接超时时间（秒）

传输配置

服务器支持MCP协议的多种传输机制：

STDIO传输（默认）

默认传输使用标准输入/输出进行通信。这非常适合本地使用以及与通过stdin/stdout进行通信的工具集成：

MCP_TRANSPORT=stdio

HTTP SSE传输（服务器发送事件）

对于基于网络的部署，你可以使用带有服务器发送事件的HTTP。这允许通过HTTP实时流式访问MCP服务器：

MCP_TRANSPORT=sse
MCP_HTTP_HOST=0.0.0.0        # 绑定到所有接口（或特定IP）
MCP_HTTP_PORT=8000           # 监听端口
MCP_HTTP_BEARER_TOKEN=your-secret-token  # 可选的认证令牌

使用带有Bearer令牌的SSE传输时，客户端必须在其请求中包含该令牌：

curl -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse

HTTP可流式传输

HTTP可流式传输提供基于HTTP的请求/响应流式通信。这非常适合Web集成和需要HTTP端点的工具：

MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0        # 绑定到所有接口（或特定IP）
MCP_HTTP_PORT=8000           # 监听端口
MCP_HTTP_BEARER_TOKEN=your-secret-token  # 可选的认证令牌

使用带有Bearer令牌的可流式传输时：

curl -H "Authorization: Bearer your-secret-token" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:8000/mcp

注意：HTTP传输需要使用jsonrpc和id字段进行正确的JSON-RPC格式化。服务器可能还需要对某些操作进行会话初始化。 有关FastMCP传输的更多信息，请参阅FastMCP文档。

🤝 贡献

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 进行更改
4. 运行测试并确保代码质量 (uv run pytest && uv run ruff check .)
5. 提交更改 (git commit -m 'Add amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打开拉取请求

📄 许可证

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