Zabbix MCP Server

🚀 Zabbix MCP Server

Zabbix MCP Server 是一個全面的模型上下文協議（MCP）服務器，它藉助 FastMCP 和 python - zabbix - utils 實現與 Zabbix 的集成。該服務器通過支持 MCP 的工具，提供對 Zabbix API 功能的完整訪問。

🚀 快速開始

此 Zabbix MCP 服務器可幫助你藉助 MCP 工具訪問 Zabbix API。按照以下步驟快速部署和使用：

1. 克隆倉庫：

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

2. 安裝依賴：

   uv sync
   

3. 配置環境變量：

   cp config/.env.example .env
   # 使用你的 Zabbix 服務器詳細信息編輯 .env
   

4. 測試安裝：

   uv run python scripts/test_server.py
   

✨ 主要特性

🏠 主機管理

• host_get - 通過高級過濾檢索主機
• host_create - 創建帶有接口和模板的新主機
• host_update - 更新現有主機配置
• host_delete - 從監控中移除主機

👥 主機組管理

• hostgroup_get - 檢索主機組
• hostgroup_create - 創建新的主機組
• hostgroup_update - 修改現有主機組
• hostgroup_delete - 移除主機組

📊 監控項管理

• item_get - 通過過濾檢索監控項
• item_create - 創建新的監控項
• item_update - 更新現有監控項
• item_delete - 移除監控項

⚠️ 觸發器管理

• trigger_get - 檢索觸發器和警報
• trigger_create - 創建新的觸發器
• trigger_update - 修改現有觸發器
• trigger_delete - 移除觸發器

📋 模板管理

• template_get - 檢索監控模板
• template_create - 創建新模板
• template_update - 更新現有模板
• template_delete - 移除模板

🚨 問題與事件管理

• problem_get - 檢索當前的問題和故障
• event_get - 獲取歷史事件
• event_acknowledge - 確認事件和問題

📈 數據檢索

• history_get - 訪問歷史監控數據
• trend_get - 檢索趨勢數據和統計信息

👤 用戶管理

• user_get - 檢索用戶賬戶
• user_create - 創建新用戶
• user_update - 更新用戶信息
• user_delete - 移除用戶賬戶

🔧 維護管理

• maintenance_get - 檢索維護週期
• maintenance_create - 安排維護窗口
• maintenance_update - 修改維護週期
• maintenance_delete - 移除維護計劃

📊 其他特性

• graph_get - 檢索圖形配置
• discoveryrule_get - 獲取發現規則
• itemprototype_get - 檢索監控項原型
• configuration_export - 導出 Zabbix 配置
• configuration_import - 導入配置
• apiinfo_version - 獲取 API 版本信息

📦 安裝指南

前提條件

• Python 3.10 或更高版本
• uv 包管理器
• 可訪問啟用了 API 的 Zabbix 服務器

快速啟動

按照上述“快速開始”部分的步驟操作即可。

💻 使用示例

基礎用法

# 獲取所有主機
host_get()

# 獲取特定組中的主機
host_get(groupids=["1"])

高級用法

# 創建一個新主機
host_create(
    host="server-01",
    groups=[{"groupid": "1"}],
    interfaces=[{
        "type": 1,
        "main": 1,
        "useip": 1,
        "ip": "192.168.1.100",
        "dns": "",
        "port": "10050"
    }]
)

# 獲取最近的問題
problem_get(recent=True, limit=10)

# 獲取歷史數據
history_get(
    itemids=["12345"],
    time_from=1640995200,
    limit=100
)

📚 詳細文檔

MCP 集成

此服務器旨在與像 Claude Desktop 這樣支持 MCP 的客戶端協同工作。詳細的集成說明請參閱 MCP_SETUP.md。

Docker 支持

使用 Docker Compose

1. 配置環境：

   cp config/.env.example .env
   # 使用你的設置編輯 .env
   

2. 使用 Docker Compose 運行：

   docker compose up -d
   

構建 Docker 鏡像

docker build -t zabbix-mcp-server .

開發

項目結構

zabbix-mcp-server/
├── src/
│   └── zabbix_mcp_server.py    # 主服務器實現
├── scripts/
│   ├── start_server.py         # 帶有驗證的啟動腳本
│   └── test_server.py          # 測試腳本
├── config/
│   ├── .env.example           # 環境配置模板
│   └── mcp.json               # MCP 客戶端配置示例
├── pyproject.toml             # Python 項目配置
├── requirements.txt           # 依賴項
├── Dockerfile                 # Docker 配置
├── docker-compose.yml         # Docker Compose 配置
├── README.md                  # 本文件
├── MCP_SETUP.md               # MCP 集成指南
├── CONTRIBUTING.md            # 貢獻指南
├── CHANGELOG.md               # 版本歷史
└── LICENSE                    # MIT 許可證

貢獻代碼

1. 分叉倉庫
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打開拉取請求

運行測試

# 測試服務器功能
uv run python scripts/test_server.py

# 使用 Docker 進行測試
docker-compose exec zabbix-mcp python scripts/test_server.py

🔧 技術細節

錯誤處理

服務器包含全面的錯誤處理機制：

• ✅ 明確報告身份驗證錯誤
• 🔒 以描述性消息阻止只讀模式違規
• ✔️ 驗證無效參數
• 🌐 正確格式化網絡和 API 錯誤
• 📝 詳細記錄日誌以便進行故障排除

安全考慮

• 🔑 儘可能使用 API 令牌而非用戶名/密碼
• 🔒 對於僅用於監控的用例，啟用只讀模式
• 🛡️ 保護好你的環境變量
• 🔐 對 Zabbix 服務器連接使用 HTTPS
• 🔄 定期輪換 API 令牌
• 📁 安全存儲配置文件

故障排除

常見問題

連接失敗：

• 驗證 ZABBIX_URL 是否正確且可訪問
• 檢查身份驗證憑據
• 確保 Zabbix API 已啟用

權限被拒：

• 驗證用戶是否具有足夠的 Zabbix 權限
• 檢查在嘗試修改數據時是否啟用了只讀模式

工具未找到：

• 確保所有依賴項都已安裝：uv sync
• 驗證 Python 版本兼容性（3.10+）

調試模式

設置環境變量以進行詳細日誌記錄：

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

依賴項

• FastMCP - MCP 服務器框架
• python - zabbix - utils - 官方 Zabbix Python 庫

📄 許可證

本項目採用 MIT 許可證 - 詳細信息請參閱 LICENSE 文件。

致謝

• Zabbix 提供的監控平臺
• Model Context Protocol 提供的集成標準
• FastMCP 提供的服務器框架

支持

• 📖 文檔
• 🐛 問題跟蹤
• 💬 討論

為 Zabbix 和 MCP 社區用心打造 ❤️