Zabbix Mcp

Zabbix MCP 服务

一个轻量级的模型上下文协议（MCP）服务，只需通过 3 个工具即可完整访问整个 Zabbix API。兼容 Zabbix 6.0+。

为什么选择 Zabbix MCP 服务？

• 完整覆盖 API - 通过统一接口访问所有 Zabbix API 方法（100+）
• 轻量级上下文 - 仅需 3 个工具，而非 50+ 个独立工具，从而最大限度减少大模型上下文
• 始终保持最新 - 自动适配当前和未来的 Zabbix API 方法
• 兼容 Zabbix 6.0+ - 支持 Zabbix 6.0、6.4、7.0 及更新版本

这 3 个工具

工具	用途
zabbix_api	执行任意 Zabbix API 方法
zabbix_api_docs	获取任意 API 方法的文档
zabbix_api_list	查找可用的 API 对象和方法

快速开始

选项 1：Claude Code 集成

添加到 Claude Code MCP 配置中：

claude mcp add zabbix \
  --env ZABBIX_URL=https://your-zabbix-server.com \
  --env ZABBIX_TOKEN=your_api_token \
  -- uvx --from git+https://github.com/mpeirone/zabbix-mcp-server@main zabbix-mcp

选项 2：使用 uv 运行

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

# Configure environment
export ZABBIX_URL=https://your-zabbix-server.com
export ZABBIX_TOKEN=your_api_token

# Start the server
uv run python scripts/start_server.py

测试连接

uv run python scripts/test_server.py

选项 3：使用 docker 运行

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

# Using docker-compose
docker compose up -d

# Or build manually
docker build -t zabbix-mcp-server .
docker run -e ZABBIX_URL=https://zabbix.example.com -e ZABBIX_TOKEN=your_token zabbix-mcp-server

环境变量

必需

变量	描述	示例
ZABBIX_URL	Zabbix 服务 URL	https://your-zabbix-server.com

身份验证（任选其一）

变量	描述
ZABBIX_TOKEN	API 令牌（推荐）
ZABBIX_USER + ZABBIX_PASSWORD	用户名和密码

安全性

变量	默认值	描述
READ_ONLY	false	设为 true 以仅允许读取操作
VERIFY_SSL	true	启用/禁用 SSL 验证
ZABBIX_API_WHITELIST	.*	以逗号分隔的正则表达式模式，用于允许 API 方法
ZABBIX_API_BLACKLIST	（空）	以逗号分隔的正则表达式模式，用于屏蔽 API 方法
ZABBIX_SKIP_VERSION_CHECK	false	跳过 Zabbix 版本兼容性检查
ZABBIX_API_TIMEOUT	30	API 请求超时时间（秒）

传输

变量	默认值	描述
ZABBIX_MCP_TRANSPORT	stdio	传输类型：stdio 或 streamable-http
ZABBIX_MCP_HOST	127.0.0.1	HTTP 服务主机（使用 streamable-http 时）
ZABBIX_MCP_PORT	8000	HTTP 服务端口（使用 streamable-http 时）
ZABBIX_MCP_STATELESS_HTTP	false	无状态 HTTP 模式
AUTH_TYPE	-	HTTP 传输必须设为 no-auth（使用 streamable-http 时）

调试

变量	默认值	描述
DEBUG	false	设为 true 以启用详细日志记录

使用示例

获取主机

zabbix_api(method='host.get', params={'output': ['hostid', 'name']})

获取问题

zabbix_api(method='problem.get', params={'output': 'extend', 'recent': True})

创建主机

zabbix_api(method='host.create', params={
    'host': 'server-01',
    'groups': [{'groupid': '1'}],
    'interfaces': [{'type': 1, 'main': 1, 'useip': 1, 'ip': '192.168.1.100', 'port': '10050'}]
})

获取方法文档

zabbix_api_docs(method='host.create')

列出可用方法

zabbix_api_list()              # All objects and methods
zabbix_api_list(object='host')  # Host methods only

安全功能

只读模式

设置 READ_ONLY=true 以阻止所有写入操作：

export READ_ONLY=true

仅允许 get、version、check 和 export 操作。

API 方法过滤

使用白名单/黑名单模式控制可调用的 API 方法：

# Allow only host.* and item.get methods
export ZABBIX_API_WHITELIST="host\..*,item\.get"

# Block all delete and create operations
export ZABBIX_API_BLACKLIST=".*\.delete,.*\.create"

两者均支持以逗号分隔的正则表达式模式。首先检查黑名单。

MCP 客户端配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "zabbix": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mpeirone/zabbix-mcp-server@main", "zabbix-mcp"],
      "env": {
        "ZABBIX_URL": "https://zabbix.example.com",
        "ZABBIX_TOKEN": "your_api_token"
      }
    }
  }
}

故障排除

连接问题

• 确认可以访问 ZABBIX_URL
• 检查身份验证凭据
• 确保已启用 Zabbix API

权限错误

• 确认 Zabbix 用户权限
• 检查是否启用了 READ_ONLY 模式

方法被阻止

如果看到“Method is not in whitelist”或“Method is blacklisted”：

• 检查 ZABBIX_API_WHITELIST 和 ZABBIX_API_BLACKLIST 模式
• 确保正则表达式模式与完整的方法名称匹配（例如，host.get）

调试模式

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

贡献

开发指南请参阅 CONTRIBUTING.md。

许可证

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

致谢

• Zabbix - 监控平台
• Model Context Protocol - 集成标准
• FastMCP - MCP 框架
• python-zabbix-utils - Zabbix 官方 Python 库