shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

zabbix-mcp

Zabbix MCP服务器是一个基于Python的模型上下文协议服务器，提供对Zabbix监控数据的可编程访问和管理功能，支持查询主机、模板、触发器、问题等资源，并具备读写操作、安全特性和多种传输方式。

article

README

🚀 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
  1. 安装依赖：
# 使用UV（推荐）
uv sync

# 或者使用pip
pip install -e .
  1. 配置环境变量：
cp .env.example .env
# 用你的Zabbix URL和凭证编辑.env
  1. 运行服务器：
# 使用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文件。

help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端