Zabbix MCP

🚀 Zabbix MCP Server

Zabbix MCP Server是一個基於Python的模型上下文協議（MCP）服務器，旨在為Zabbix監控數據和管理功能提供高級的可編程訪問。它提供了一個現代化的API，用於查詢、自動化和集成Zabbix資源，如主機、模板、觸發器、監控項、問題、事件、用戶、代理、維護週期等。該服務器支持讀寫操作，具備強大的安全特性，適合與AI助手、自動化工具、儀表盤和自定義監控工作流集成。

🚀 快速開始

Zabbix MCP Server為用戶提供了便捷的方式來訪問和管理Zabbix監控系統的數據和功能。以下是開始使用該服務器的基本步驟和相關信息。

✨ 主要特性

核心特性

• 可靈活過濾查詢Zabbix的主機、模板、監控項、觸發器和主機組。
• 可按嚴重程度過濾檢索問題、事件和警報。
• 訪問監控項的歷史和趨勢數據。
• 監控觸發器狀態和問題嚴重程度。
• 管理維護週期和計劃停機時間。
• 檢索用戶宏和配置數據。
• 獲取SLA和服務信息。

管理操作

• 創建、更新和刪除主機、模板和主機組（如果啟用）。
• 管理觸發器、監控項和發現規則。
• 配置維護週期和用戶宏。
• 在監控主機上執行腳本。
• 確認事件並關閉問題。
• 創建和管理用戶及代理。
• 支持對主機和模板進行批量操作。

高級功能

• 速率限制和API安全功能。
• 只讀模式，限制所有寫操作以確保安全監控。
• HTTP傳輸的Bearer令牌認證。
• 全面的日誌記錄和審計跟蹤。
• 支持SSL/TLS和可配置的超時設置。
• 多種傳輸選項（STDIO、SSE、HTTP）。
• 可選的Sentry集成，用於錯誤跟蹤。

📦 安裝指南

前提條件

• Python 3.11 至 3.14
• 訪問Zabbix服務器（5.4+）
• 有效的Zabbix API令牌或具有適當權限的用戶憑證

從PyPI快速安裝

最簡單的開始方式是從PyPI安裝：

# 使用UV（推薦）
uvx zabbix-mcp

# 或者使用pip
pip install zabbix-mcp

在運行服務器之前，請記得為你的Zabbix實例配置環境變量：

# 創建環境配置
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. 安裝依賴：

# 使用UV（推薦）
uv sync

# 或者使用pip
pip install -e .

3. 配置環境變量：

cp .env.example .env
# 用你的Zabbix URL和憑證編輯.env

4. 運行服務器：

# 使用UV
uv run python run_server.py

# 或者直接使用Python
python run_server.py

# 或者使用已安裝的腳本
zabbix-mcp

使用Docker

GitHub Packages上提供了Docker鏡像，便於部署。

# 普通STDIO鏡像
docker pull ghcr.io/mhajder/zabbix-mcp:latest

# 用於Open WebUI的MCPO鏡像
docker pull ghcr.io/mhajder/zabbix-mcpo:latest

開發環境設置

若要使用額外工具進行開發：

# 克隆並安裝開發依賴
git clone https://github.com/mhajder/zabbix-mcp.git
cd zabbix-mcp
uv sync --group dev

# 運行測試
uv run pytest

# 運行覆蓋率測試
uv run pytest --cov=src/

# 運行代碼檢查和格式化
uv run ruff check .
uv run ruff format .

# 設置預提交鉤子
uv run pre-commit install

📚 詳細文檔

配置

環境變量

# Zabbix連接詳情
ZABBIX_URL=https://zabbix.example.com/api_jsonrpc.php

# 認證 - 使用令牌或用戶名/密碼
# API令牌（Zabbix 5.4+首選）
ZABBIX_TOKEN=your-api-token
# 或者 用戶名/密碼（適用於舊版本）
# ZABBIX_USER=Admin
# ZABBIX_PASSWORD=zabbix

# SSL配置
ZABBIX_VERIFY_SSL=true
ZABBIX_TIMEOUT=30
ZABBIX_SKIP_VERSION_CHECK=false

# 只讀模式
# 將READ_ONLY_MODE設置為true以禁用所有寫操作（創建、更新、刪除）
READ_ONLY_MODE=false

# 禁用標籤
# 以逗號分隔的標籤列表，用於禁用工具（默認為空）
# 示例：DISABLED_TAGS=host,user,maintenance
DISABLED_TAGS=

# 日誌配置
LOG_LEVEL=INFO

# 速率限制
# 將RATE_LIMIT_ENABLED設置為true以啟用速率限制
RATE_LIMIT_ENABLED=false
RATE_LIMIT_MAX_REQUESTS=60
RATE_LIMIT_WINDOW_MINUTES=1

# Sentry錯誤跟蹤（可選）
# 設置SENTRY_DSN以啟用錯誤跟蹤和性能監控
# SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789
# 可選的Sentry配置
# SENTRY_TRACES_SAMPLE_RATE=1.0
# SENTRY_SEND_DEFAULT_PII=true
# SENTRY_ENVIRONMENT=production
# SENTRY_RELEASE=1.2.3
# SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0
# SENTRY_PROFILE_LIFECYCLE=trace
# SENTRY_ENABLE_LOGS=true

# MCP傳輸配置
# 傳輸類型：'stdio'（默認）、'sse'（服務器發送事件）或'http'（HTTP可流式傳輸）
MCP_TRANSPORT=stdio

# HTTP傳輸設置（當MCP_TRANSPORT=sse或MCP_TRANSPORT=http時使用）
# 綁定HTTP服務器的主機（默認：0.0.0.0表示所有接口）
MCP_HTTP_HOST=0.0.0.0
# 綁定HTTP服務器的端口（默認：8000）
MCP_HTTP_PORT=8000
# 可選的Bearer令牌用於認證（留空表示無認證）
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

速率限制

服務器支持速率限制，以控制API使用並防止濫用。如果啟用，將使用滑動窗口算法對每個客戶端的請求進行限制。 在你的.env文件中設置以下環境變量來啟用速率限制：

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=100   # 每個窗口允許的最大請求數
RATE_LIMIT_WINDOW_MINUTES=1   # 窗口大小（分鐘）

如果RATE_LIMIT_ENABLED設置為true，服務器將應用速率限制中間件。根據你的環境需要調整RATE_LIMIT_MAX_REQUESTS和RATE_LIMIT_WINDOW_MINUTES。

Sentry錯誤跟蹤與監控（可選）

服務器可選支持Sentry進行錯誤跟蹤、性能監控和調試。Sentry集成是完全可選的，只有在配置後才會初始化。

安裝

要啟用Sentry監控，安裝可選依賴：

# 使用UV（推薦）
uv sync --extra sentry

配置

通過在你的.env文件中設置SENTRY_DSN環境變量來啟用Sentry：

# 必需：你的項目的Sentry DSN
SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789

# 可選：性能監控採樣率（0.0 - 1.0，默認：1.0）
SENTRY_TRACES_SAMPLE_RATE=1.0

# 可選：包含個人身份信息（默認：true）
SENTRY_SEND_DEFAULT_PII=true

# 可選：環境名稱（例如，"production"、"staging"）
SENTRY_ENVIRONMENT=production

# 可選：發佈版本（如果未設置，將從包中自動檢測）
SENTRY_RELEASE=1.2.3

# 可選：分析 - 連續分析採樣率（0.0 - 1.0，默認：1.0）
SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

# 可選：分析 - 分析生命週期模式（默認："trace"）
# 選項："all"、"continuation"、"trace"
SENTRY_PROFILE_LIFECYCLE=trace

# 可選：啟用日誌捕獲作為麵包屑和事件（默認：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    # 啟用SSL證書驗證
ZABBIX_TIMEOUT=30         # 連接超時時間（秒）

傳輸配置

服務器支持MCP協議的多種傳輸機制：

STDIO傳輸（默認）

默認傳輸使用標準輸入/輸出進行通信。這非常適合本地使用以及與通過stdin/stdout進行通信的工具集成：

MCP_TRANSPORT=stdio

HTTP SSE傳輸（服務器發送事件）

對於基於網絡的部署，你可以使用帶有服務器發送事件的HTTP。這允許通過HTTP即時流式訪問MCP服務器：

MCP_TRANSPORT=sse
MCP_HTTP_HOST=0.0.0.0        # 綁定到所有接口（或特定IP）
MCP_HTTP_PORT=8000           # 監聽端口
MCP_HTTP_BEARER_TOKEN=your-secret-token  # 可選的認證令牌

使用帶有Bearer令牌的SSE傳輸時，客戶端必須在其請求中包含該令牌：

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

HTTP可流式傳輸

HTTP可流式傳輸提供基於HTTP的請求/響應流式通信。這非常適合Web集成和需要HTTP端點的工具：

MCP_TRANSPORT=http
MCP_HTTP_HOST=0.0.0.0        # 綁定到所有接口（或特定IP）
MCP_HTTP_PORT=8000           # 監聽端口
MCP_HTTP_BEARER_TOKEN=your-secret-token  # 可選的認證令牌

使用帶有Bearer令牌的可流式傳輸時：

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傳輸需要使用jsonrpc和id字段進行正確的JSON-RPC格式化。服務器可能還需要對某些操作進行會話初始化。 有關FastMCP傳輸的更多信息，請參閱FastMCP文檔。

🤝 貢獻

1. 分叉倉庫
2. 創建功能分支 (git checkout -b feature/amazing-feature)
3. 進行更改
4. 運行測試並確保代碼質量 (uv run pytest && uv run ruff check .)
5. 提交更改 (git commit -m 'Add amazing feature')
6. 推送到分支 (git push origin feature/amazing-feature)
7. 打開拉取請求

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。