使用说明

Zabbix MCP服务器

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

为什么选择Zabbix MCP服务器？

API全面覆盖 -通过统一接口访问每个Zabbix API方法（100+）
轻量级上下文 -只有3个工具，而不是50多个单独的工具，使LLM上下文最小化
始终保持最新 -自动使用当前和未来的Zabbix API方法
Zabbix 6.0+兼容 -支持Zabbix 6.0、6.4、7.0和更新版本

三种工具

工具	目的
`zabbix_api`	执行任何Zabbix API方法
`zabbix_api_docs`	获取任何API方法的文档
`zabbix_api_list`	发现可用的API对象和方法

快速开始

选项1:Claude代码集成

添加到您的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：使用紫外线跑步

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方法的逗号分隔regex模式
`ZABBIX_API_BLACKLIST`	（空）	阻止的API方法的逗号分隔regex模式
`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`	-	必须是 `no-auth` 用于HTTP传输（使用时 `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客户端配置

克劳德桌面版

添加 ~/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 模式已启用

方法已阻止

如果您看到“方法不在白名单中”或“方法被列入黑名单”：

审查 ZABBIX_API_WHITELIST 和 ZABBIX_API_BLACKLIST 模式
确保正则表达式模式与完整方法名匹配（例如。， host.get)

调试模式

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

贡献

看贡献.md 发展指南。

许可证

GPLv3许可证-请参阅许可证了解详情。

致谢

扎比克斯 -监控平台
模型上下文协议 -集成标准
FastMCP -MCP框架
python zabbix实用工具 -Zabbix官方Python库