Zabbix MCP

Zabbix MCP Server 是一个基于 Python 的 Model Context Protocol（MCP）服务，旨在为 Zabbix 监控数据和管理功能提供高级、可编程的访问能力。它提供现代化 API，用于查询、自动化和集成 Zabbix 资源，例如主机、模板、触发器、监控项、问题、事件、用户、代理、维护时段等。该服务支持读写操作，具备完善的安全功能，适用于与 AI 助手、自动化工具、仪表板和自定义监控工作流集成。

✨ 功能

核心功能

• 通过灵活的筛选条件查询 Zabbix 主机、模板、监控项、触发器和主机群组
• 按严重性筛选并检索问题、事件和警报
• 访问受监控监控项的历史数据和趋势数据
• 监控触发器状态和问题严重性
• 管理维护时段和计划停机时间
• 检索用户宏和配置数据
• 获取 SLA 和服务信息

管理操作

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

高级功能

• 速率限制和 API 安全功能
• 只读模式，可限制所有写操作，实现安全监控
• 可选的工具搜索转换功能，适用于大型工具目录
• HTTP 传输的 Bearer token 身份验证
• 完善的日志记录和审计跟踪
• SSL/TLS 支持和可配置超时
• 多种传输选项（STDIO、SSE、HTTP）
• 可选的 Sentry 错误跟踪集成

🚀 安装

前置条件

• Python 3.11 至 3.15
• 能够访问 Zabbix 服务。支持 6.0 至 7.4 版本——这是 zabbix-utils 客户端接受的版本范围；除非设置 ZABBIX_SKIP_VERSION_CHECK=true，否则客户端会拒绝连接范围之外的版本
• 具有相应权限的有效 Zabbix API token 或用户凭据

从 PyPI 快速安装

最简单的入门方式是从 PyPI 安装：

# Using UV (recommended)
uvx zabbix-mcp

# Or using pip
pip install zabbix-mcp

运行服务前，请务必为 Zabbix 实例配置环境变量：

# Create environment configuration
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. 安装依赖：

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. 配置环境变量：

cp .env.example .env
# Edit .env with your Zabbix URL and credentials

4. 运行服务：

# Using UV (recommended)
uv run zabbix-mcp

# Or using the installed command directly
zabbix-mcp

使用 Docker

GitHub Packages 上提供了 Docker 镜像，便于部署。该镜像在端口 8000（/mcp）上运行 HTTP Streamable 传输。

docker pull ghcr.io/mhajder/zabbix-mcp:latest

Open WebUI

Open WebUI 0.6.31 及更高版本可直接连接该镜像；不再发布单独的 MCPO 镜像（ghcr.io/mhajder/zabbix-mcpo）。在 Open WebUI 中， 前往 管理设置 > 集成 > 外部工具服务，添加一个类型为 MCP (Streamable HTTP) 的连接， URL 设为 http://<host>:8000/mcp，并将 Bearer 身份验证设置为你的 MCP_HTTP_BEARER_TOKEN。

开发环境设置

如需使用其他工具进行开发：

# Clone and install with development dependencies
git clone https://github.com/mhajder/zabbix-mcp.git
cd zabbix-mcp
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run ty check .

# Setup prek hooks
uv run prek install

🔧 配置

环境变量

# Zabbix Connection Details
ZABBIX_URL=https://zabbix.example.com/api_jsonrpc.php

# Authentication - use EITHER token OR user/password
# API Token (preferred over user/password)
ZABBIX_TOKEN=your-api-token
# OR Username/Password (for older versions)
# ZABBIX_USER=Admin
# ZABBIX_PASSWORD=zabbix

# SSL Configuration
ZABBIX_VERIFY_SSL=true
ZABBIX_TIMEOUT=30
ZABBIX_SKIP_VERSION_CHECK=false

# Read-Only Mode
# Set READ_ONLY_MODE true to disable all write operations (create, update, delete)
READ_ONLY_MODE=false

# Disabled Tags
# Comma-separated list of tags to disable tools for (empty by default)
# Example: DISABLED_TAGS=host,user,maintenance
DISABLED_TAGS=

# Logging Configuration
LOG_LEVEL=INFO

# Rate Limiting
# Set RATE_LIMIT_ENABLED true to enable rate limiting
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=60
RATE_LIMIT_WINDOW_MINUTES=1

# Tool Search Transform (Optional)
# Set TOOL_SEARCH_ENABLED true to replace full tool listing with search tools
TOOL_SEARCH_ENABLED=false
# Search strategy: bm25 (natural language) or regex (pattern matching)
TOOL_SEARCH_STRATEGY=bm25
# Maximum number of matching tools returned by search_tools
TOOL_SEARCH_MAX_RESULTS=5

# Sentry Error Tracking (Optional)
# Set SENTRY_DSN to enable error tracking and performance monitoring
# SENTRY_DSN=https://[email protected]/6789
# Optional Sentry configuration
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=false
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP Transport Configuration
# Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable)
# 'streamable-http' is accepted as an alias for 'http'. Any other value stops
# the server at startup.
MCP_TRANSPORT=stdio

# HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)
# Host to bind the HTTP server (default: 127.0.0.1)
# MCP_HTTP_HOST=127.0.0.1
# Port to bind the HTTP server (default: 8000)
# MCP_HTTP_PORT=8000
# Optional bearer token for authentication (leave empty for no auth)
# 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

面向大型工具集的工具搜索

对于包含大量工具的服务器，FastMCP 工具搜索可以缩减提示词的大小。 启用后，list_tools 会返回两个合成工具：

• search_tools：查找匹配的工具并返回其完整架构
• call_tool：按名称执行任何已发现的工具

通过以下方式启用：

TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25      # bm25 or regex
TOOL_SEARCH_MAX_RESULTS=8      # optional, default is 5

bm25 支持自然语言查询，而 regex 使用正则表达式 pattern 输入，以便进行确定性匹配。

工具搜索会遵循现有的可见性控制（只读模式和禁用的标签）。

速率限制

服务器支持速率限制，以控制 API 使用量并防止滥用。启用后，服务器会使用滑动窗口算法，按客户端限制请求数量。

在 .env 文件中设置以下环境变量，即可启用速率限制：

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=60    # Maximum requests allowed per window (default: 60)
RATE_LIMIT_WINDOW_MINUTES=1   # Window size in minutes

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

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

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

安装

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

# Using UV (recommended)
uv sync --extra sentry

配置

在 .env 文件中设置 SENTRY_DSN 环境变量，即可启用 Sentry：

# Required: Sentry DSN for your project
SENTRY_DSN=https://[email protected]/6789

# Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)
SENTRY_TRACES_SAMPLE_RATE=1.0

# Optional: Include personally identifiable information (default: false).
# When true, tool inputs and outputs are sent to Sentry.
SENTRY_SEND_DEFAULT_PII=false

# Optional: Environment name (e.g., "production", "staging")
SENTRY_ENVIRONMENT=production

# Optional: Release version (auto-detected from package if not set)
SENTRY_RELEASE=1.2.3

# Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

# Optional: Profiling - lifecycle mode for profiling (default: "trace")
# Options: "all", "continuation", "trace"
SENTRY_PROFILE_LIFECYCLE=trace

# Optional: Enable log capture as breadcrumbs and events (default: 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    # Enable SSL certificate verification
ZABBIX_TIMEOUT=30         # Connection timeout in seconds

传输配置

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

STDIO 传输（默认）

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

MCP_TRANSPORT=stdio

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

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

MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

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

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

HTTP 可流式传输

HTTP 可流式传输提供基于 HTTP 的通信，并支持请求/响应流式传输。它非常适合 Web 集成，以及需要 HTTP 端点的工具：

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

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

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 传输需要正确的 JSON-RPC 格式，其中包含 jsonrpc 和 id 字段。对于某些操作，服务器还可能要求先初始化会话。

健康检查端点

两种 HTTP 传输方式（sse 和 http）都提供 GET /health，当服务正在处理请求时，会返回 200 ok。 该端点不需要承载令牌，也不会联系 Zabbix，因此 Zabbix 中断不会导致 MCP 服务被标记为不健康。 Docker 镜像的 HEALTHCHECK 使用此端点：

curl http://localhost:8000/health

有关 FastMCP 传输方式的更多信息，请参阅 FastMCP 文档。

🤝 参与贡献

欢迎贡献。开发环境设置、检查和提交消息格式请参阅 CONTRIBUTING.md，报告 Bug 和提交功能请求请使用问题模板。

发现安全问题？请按照 SECURITY.md 中的说明私下报告。

📜 许可证

MIT 许可证——详情请参阅 LICENSE。