使用说明

Zabbix MCP服务器

MCP（模型上下文协议）服务器，通过带有OpenAPI 3.1的REST API将LLM系统与Zabbix连接。

🚀 特性

快速API：具有自动OpenAPI 3.1文档的高性能REST服务器
MCP协议：完全支持模型上下文协议（兼容Claude Desktop）
双协议支持：同时使用REST API和MCP/SSE端点
开放式WebUI兼容：专为端口8000上的开放式webui集成而设计
Zabbix JSON-RPC客户端：与Zabbix API完成沟通
托管身份验证：支持API令牌或自动续订的用户名/密码
只读模式：可选安全功能，可防止在Zabbix上进行写操作
完整的API：所有Zabbix操作有40多个端点
- 完整CRUD 用于主机、项目、触发器、模板、主机组
- 监控：问题、历史、趋势、事件、警报
- 自动化：维护、操作、脚本、发现
- 管理：用户、服务、代理、图表、仪表板
详细说明：每个端点都有完整的文档，以方便LLM的使用
CORS已启用：已准备好进行web集成
交互式文档：包括Swagger UI和ReDoc
LLM就绪：针对LLM系统（OpenAI、Claude等）的工具调用进行了优化

📋 先决条件

Python 3.8或更高版本
访问启用API的Zabbix服务器
具有适当权限的Zabbix用户凭据

🔧 安装

克隆或导航到项目目录：
```
cd ZABBIX-MCP
```
创建Python虚拟环境：
```
python -m venv venv
```
激活虚拟环境：
- 窗户：
```
venv\Scripts\activate
```
- Linux/Mac：
```
source venv/bin/activate
```
安装依赖项：
```
pip install -r requirements.txt
```

配置环境变量：

复制 .env.example 文件到 .env:
```
copy .env.example .env
```

编辑 .env 使用Zabbix配置：

ZABBIX_URL=https://your-zabbix-server.com/zabbix/api_jsonrpc.php
# Use API token (recommended method)
ZABBIX_API_TOKEN=your_api_token_here
# Or username/password (legacy method)
# ZABBIX_USER=your_username
# ZABBIX_PASSWORD=your_password

# SSL/TLS verification (set to false if using self-signed certificates)
ZABBIX_VERIFY_SSL=true

# Read-Only Mode (set to true to prevent any write operations on Zabbix)
ZABBIX_READONLY=false

SERVER_HOST=0.0.0.0
SERVER_PORT=8000

如何在Zabbix中获得API代币：

以管理员身份登录Zabbix
转到管理→ 将军→ API令牌
点击“创建API令牌”
选择用户并设置过期时间（或为永久令牌留空）
复制生成的令牌并将其插入 .env 文件

🚀 启动服务器

python main.py

或直接与uvicorn混合：

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

服务器将在以下时间可用 http://localhost:8000

📚 API文档

服务器启动后，您可以访问交互式文档：

Swagger 用户界面: http://localhost:8000/docs
ReDoc: http://localhost:8000/redoc
OpenAPI架构: http://localhost:8000/openapi.json

🔒 只读模式

服务器支持 只读模式 这可以防止对Zabbix进行任何写入操作。这对以下情况很有用：

安全：防止意外修改您的监控基础架构
训练：允许用户在不破坏配置的情况下进行探索和学习
审计：为监控和报告目的提供只读访问
LLM安全：防止AI助手进行未经授权的更改

如何启用只读模式

设置 ZABBIX_READONLY 标记为 true 在你的 .env 文件：

ZABBIX_READONLY=true

什么被阻止

启用只读模式时，所有写入操作都会被阻止，包括：

创建、更新或删除主机
创建、更新或删除项目、触发器、模板
创建或删除主机组
承认问题
创建或删除维护窗口
创建、更新或删除用户
创建或删除操作
任何其他修改Zabbix数据的操作

此外，写入端点在OpenAPI文档中会自动隐藏 （Swagger UI和ReDoc），因此LLM系统和API使用者只能看到可用的只读操作。

什么仍然有效

所有读取操作继续正常工作：

列出主机、项目、触发器、问题
查看历史数据和趋势
检查API版本和身份验证
查看事件、警报、图表、仪表板
所有GET操作

错误响应

在只读模式下尝试写入操作时，API返回：

状态码：403禁止

响应:

{
  "error": "Operation Forbidden",
  "detail": "Cannot perform 'operation_name' operation: System is in read-only mode. Set ZABBIX_READONLY=false in .env to enable write operations."
}

🤖 MCP/Claude桌面集成

此服务器实现 模型上下文协议（MCP） 与Claude Desktop和其他人工智能助手集成。

什么是MCP？

MCP（模型上下文协议）是一种基于JSON-RPC 2.0的协议，允许像克劳德这样的人工智能助手发现和使用外部工具。它提供：

标准化工具发现 -AI可以查询可用操作
动态能力 -工具根据服务器模式进行调整（只读与完全访问）
流媒体支持 -SSE（服务器发送事件）用于持久连接

MCP端点

POST/mcp -JSON-RPC 2.0请求的主MCP端点（初始化、工具/列表、工具/调用）
GET/sse -用于持久连接和服务器通知的服务器发送事件端点

MCP SSE协议（完全符合）：

Claude Desktop打开SSE连接 /sse
服务器必须发送 event: endpoint 使用JSON-RPC端点URL（例如。， http://localhost:8000/mcp)
客户端从该SSE消息中发现端点URL
客户端向发现的端点发送JSON-RPC请求：
- initialize → 服务器具有响应能力
- tools/list → 服务器使用可用工具进行响应
- tools/call → 服务器执行操作并响应
SSE连接始终保持打开状态，以接收服务器到客户端的通知
保持活动消息(: keepalive)每30秒发送一次以保持连接

为什么选择SSE？

启用动态端点发现（客户端通过SSE学习URL）
为服务器提供持久通道→客户端通知
允许服务器在状态更改时推送更新（例如，新工具可用）

Claude桌面设置

找到Claude Desktop配置目录:
- 窗户： %APPDATA%\Claude\claude_desktop_config.json
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux： ~/.config/Claude/claude_desktop_config.json
替代：对于较新的Claude Desktop版本，您也可以使用 mcp.json 在同一个目录中。
将此服务器添加到配置中:
```
{
  "mcpServers": {
    "zabbix": {
      "url": "http://localhost:8000/sse"
    }
  }
}
```
您还可以复制提供的 mcp.json 文件。

注：这 url 指向SSE端点。Claude Desktop通过SSE连接并自动发现JSON-RPC端点(/mcp)从 event: endpoint 消息。
重新启动克劳德桌面 加载新的服务器配置

可用的MCP工具

只读工具 （始终可用）：

get_zabbix_version -获取Zabbix API版本
get_hosts -列出所有具有筛选器的主机
get_host_by_name -按名称获取主机详细信息
get_problems -获取活动问题
get_items -获取监控项目
get_triggers -获取已配置的触发器
get_history -获取项目历史数据
get_events -获取Zabbix事件
get_hostgroups -列出主机组
get_templates -列出模板
get_maintenances -列出维护窗口
get_users -列出Zabbix用户
get_alerts -获取警报历史记录

编写工具 （禁用时 ZABBIX_READONLY=true):

create_host -创建新主机
delete_host -删除主机
acknowledge_event -确认事件/问题
create_maintenance -创建维护窗口

测试MCP集成

# Test MCP initialization
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

# Test tool discovery
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Test tool execution - Get Zabbix version
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_zabbix_version","arguments":{}}}'

# Test tool execution - Get hosts
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"get_hosts","arguments":{}}}'

# Test SSE endpoint
curl http://localhost:8000/sse
# Expected output:
# event: endpoint
# data: http://localhost:8000/mcp
# 
# event: message
# data: {"jsonrpc":"2.0","method":"notifications/message","params":{"level":"info","logger":"mcp-server","data":"Zabbix MCP server ready"}}
# 
# : keepalive
# (connection stays open)

双协议支持

此服务器支持 OpenAPI REST和MCP 同时：

OpenAPI REST (/api/*)-对于web客户端、工具、直接API访问：

自动记录 /docs 和 /redoc
标准HTTP方法（GET、POST、PUT、DELETE）
JSON请求/响应格式
完成CRUD操作

MCP协议 (/mcp, /sse)-对于像Claude Desktop这样的人工智能助手：

JSON-RPC 2.0协议
SSE用于端点发现和通知
工具发现和动态功能
100%符合MCP规范
AI优化工具描述

两个协议都尊重 ZABBIX_READONLY 配置。选择最适合您用例的协议。

🔌 主要终点

系统

GET /health -服务器健康检查
GET /api/version -Zabbix API版本

认证

POST /api/auth -使用Zabbix进行身份验证

主机（完整管理）

GET /api/hosts -列出所有主机
GET /api/hosts/{hostname} -特定主机的详细信息
POST /api/hosts -创建新主机
PUT /api/hosts/{hostid} -更新主机
DELETE /api/hosts/{hostid} -删除主机
POST /api/hosts/{hostid}/enable -启用监控
POST /api/hosts/{hostid}/disable -禁用监控

项目（监控指标）

GET /api/items -列出监控项目
POST /api/items -创建新项目
DELETE /api/items/{itemid} -删除项目

触发器（警报条件）

GET /api/triggers -使用可选筛选器列出触发器
POST /api/triggers -创建新触发器
DELETE /api/triggers/{triggerid} -删除触发器

问题（活跃问题）

GET /api/problems -当前问题
POST /api/problems/acknowledge -承认问题

历史与趋势（历史数据）

POST /api/history -项目的详细历史数据
GET /api/trends -每小时汇总数据（趋势）

事件（系统事件）

GET /api/events -Zabbix日志中的事件

主办团体（组织团体）

GET /api/hostgroups -列出主机组
POST /api/hostgroups -创建新组
DELETE /api/hostgroups/{groupid} -删除组

模板（可重用配置）

GET /api/templates -列出Zabbix模板
POST /api/templates -创建新模板
DELETE /api/templates/{templateid} -删除模板

维护（维护窗口）

GET /api/maintenances -列出维护周期
POST /api/maintenances -创建定期维护
DELETE /api/maintenances/{maintenanceid} -删除维护

用户和访问（用户和访问）

GET /api/users -列出Zabbix用户

警报（已发送通知）

GET /api/alerts -已发送通知的历史记录

动作（自动动作）

GET /api/actions -列出配置的自动操作

服务（IT/商业服务）

GET /api/services -业务服务和SLA

图形与可视化（可视化）

GET /api/graphs -配置的图形
GET /api/maps -网络地图
GET /api/dashboards -已配置的仪表板

脚本（远程自动化）

GET /api/scripts -列出可用脚本
POST /api/scripts/{scriptid}/execute -在主机上执行脚本

代理（分布式监控）

GET /api/proxies -列出Zabbix代理

发现（自动发现）

GET /api/discovery/rules -低级发现规则
GET /api/discovery/hosts -从网络中发现的主机
GET /api/discovery/services -从网络中发现的服务

通用（高级呼叫）

POST /api/call -Zabbix API的通用调用

💡 用法示例

获取Zabbix API版本

curl http://localhost:8000/api/version

获取所有主机

curl http://localhost:8000/api/hosts

获取当前问题

curl http://localhost:8000/api/problems

创建新主机

curl -X POST http://localhost:8000/api/hosts \
  -H "Content-Type: application/json" \
  -d '{
    "host": "New-Server-01",
    "groups": [{"groupid": "2"}],
    "interfaces": [{
      "type": 1,
      "main": 1,
      "useip": 1,
      "ip": "192.168.1.100",
      "dns": "",
      "port": "10050"
    }]
  }'

创建监控项

curl -X POST http://localhost:8000/api/items \
  -H "Content-Type: application/json" \
  -d '{
    "hostid": "10001",
    "name": "CPU Load",
    "key": "system.cpu.load[,avg1]",
    "type": 0,
    "value_type": 0,
    "delay": "1m"
  }'

承认问题

curl -X POST http://localhost:8000/api/problems/acknowledge \
  -H "Content-Type: application/json" \
  -d '{
    "eventids": ["12345"],
    "message": "Working on it",
    "action": 6
  }'

创建定期维护

curl -X POST http://localhost:8000/api/maintenances \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Weekend Maintenance",
    "active_since": 1735344000,
    "active_till": 1735387200,
    "hostids": ["10001", "10002"]
  }'

获取严重性较高的活动触发器

curl "http://localhost:8000/api/triggers?active_only=true&min_severity=4"

获取历史数据

curl -X POST http://localhost:8000/api/history \
  -H "Content-Type: application/json" \
  -d '{
    "itemids": ["23456"],
    "history_type": 0,
    "limit": 100
  }'

通用Zabbix API调用

curl -X POST http://localhost:8000/api/call \
  -H "Content-Type: application/json" \
  -d '{
    "method": "host.get",
    "params": {
      "output": ["hostid", "host"],
      "limit": 10
    }
  }'

🔗 与Open WebUI集成

该服务器旨在与开放式webui一起使用。一旦开始：

配置openwebui以使用端点： http://localhost:8000
服务器自动公开OpenAPI 3.1文档
所有端点都有文档记录，可以随时使用

🛠️ 发展

项目结构

ZABBIX-MCP/
├── main.py                       # Main FastAPI server with REST and MCP endpoints
├── mcp_server.py                 # MCP protocol implementation
├── zabbix_client.py              # Client for Zabbix API
├── config.py                     # Application configuration
├── requirements.txt              # Python dependencies
├── .env.example                  # Configuration template
├── mcp.json                      # Claude Desktop MCP configuration
├── README.md                     # This documentation
├── LLM_GUIDE.md                  # Guide for LLM systems on endpoint usage
├── MCP_QUICKSTART.md             # Quick start guide for MCP integration
├── LICENSE                       # MIT License
├── routers/                      # API route modules
│   ├── __init__.py
│   ├── hosts.py
│   ├── items.py
│   ├── triggers.py
│   ├── problems.py
│   ├── history.py
│   ├── system.py
│   └── other.py
└── .env                          # Local configuration (not committed)

添加新端点

在中添加该方法 zabbix_client.py 如有必要
在中创建端点 main.py 随着 @app.get() 或 @app.post() 装饰器
使用Pydantic模型进行请求/响应验证
手柄 ZabbixAPIError 例外

🔒 安全

身份验证： 服务器同时支持API令牌和用户名/密码
- 推荐： 使用API令牌（更安全，可以轻松撤销）
- 遗产： 用户名/密码（令牌在1小时后过期）
凭据通过环境变量进行管理
永远不要承诺 .env 文件到存储库
在生产环境中使用HTTPS保护凭据
考虑为MCP服务器实施身份验证
API令牌可以在Zabbix中配置到期日期

📝 备注

服务器同时支持这两种功能 API令牌 （推荐）和 用户名/密码 用于身份验证
API令牌不会过期（如果在Zabbix中以这种方式配置），用户名/密码中的令牌将在1小时后过期
服务器禁用Zabbix客户端的SSL验证(verify=False).在生产中，配置适当的证书。
HTTP请求超时设置为30秒。

🐛 故障排除

Zabbix连接错误

确认：

Zabbix URL正确且可访问
凭据正确
Zabbix用户拥有必要的权限

端口8000已在使用中

更改端口 .env 文件：

SERVER_PORT=8080

📄 许可证

MIT许可证

🤝 贡献

欢迎投稿、问题和功能请求！