Observium MCP

🚀 Observium MCP 服務器

這是一個 模型上下文協議 (MCP) 服務器，它將 Observium CE 網絡監控數據提供給像 Claude 這樣的大語言模型，支持通過自然語言查詢設備狀態、網絡流量、傳感器讀數、警報和歷史趨勢等信息。

🚀 快速開始

本項目旨在讓你能夠利用大語言模型（如Claude）對Observium CE的網絡監控數據進行自然語言查詢。通過以下步驟，你可以快速搭建並使用此服務器。

✨ 主要特性

• 設備管理：列出並查詢受監控設備的狀態、正常運行時間和硬件信息。
• 網絡端口：查看接口狀態、流量速率和利用率。
• 傳感器：獲取溫度、電壓、頻率及其他傳感器數據。
• 警報：查詢活動和歷史警報並查看摘要。
• 趨勢：從 RRD 數據中檢索歷史指標（負載、CPU、內存）。

📦 安裝指南

1. 克隆倉庫

git clone https://github.com/kdesch5000/observium-mcp.git
cd observium-mcp

2. 創建虛擬環境

python3 -m venv venv
source venv/bin/activate

3. 安裝依賴

pip install -r requirements.txt

4. 配置環境

複製示例配置文件並使用你的 Observium 數據庫憑證進行編輯：

cp config.example.env .env

編輯 .env 文件並設置以下內容：

# 數據庫連接（如果是遠程連接，請使用 SSH 隧道）
OBSERVIUM_DB_HOST=localhost
OBSERVIUM_DB_PORT=3306
OBSERVIUM_DB_NAME=observium
OBSERVIUM_DB_USER=observium
OBSERVIUM_DB_PASS=your_database_password

# RRD 數據路徑（在 Observium 服務器上）
OBSERVIUM_RRD_PATH=/opt/observium/rrd

# 可選：用於遠程 RRD 訪問的 SSH 配置
# 如果 MCP 服務器與 Observium 運行在不同的機器上，
# 設置這些參數以啟用基於 SSH 的 RRD 文件訪問來獲取趨勢數據
# OBSERVIUM_RRD_SSH_HOST=observium.example.com
# OBSERVIUM_RRD_SSH_USER=pi
# OBSERVIUM_RRD_SSH_PORT=22

💻 使用示例

使用 Claude Code

將以下內容添加到你的 Claude Code MCP 配置文件 (~/.claude/claude_code_config.json) 中：

{
  "mcpServers": {
    "observium": {
      "command": "python",
      "args": ["-m", "observium_mcp.server"],
      "cwd": "/path/to/observium-mcp/src",
      "env": {
        "OBSERVIUM_DB_HOST": "localhost",
        "OBSERVIUM_DB_NAME": "observium",
        "OBSERVIUM_DB_USER": "observium",
        "OBSERVIUM_DB_PASS": "your_password",
        "OBSERVIUM_RRD_PATH": "/opt/observium/rrd"
      }
    }
  }
}

使用 Claude Desktop

將以下內容添加到你的 Claude Desktop 配置文件中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "observium": {
      "command": "python",
      "args": ["-m", "observium_mcp.server"],
      "cwd": "/path/to/observium-mcp/src",
      "env": {
        "OBSERVIUM_DB_HOST": "your_observium_host",
        "OBSERVIUM_DB_NAME": "observium",
        "OBSERVIUM_DB_USER": "observium",
        "OBSERVIUM_DB_PASS": "your_password",
        "OBSERVIUM_RRD_PATH": "/opt/observium/rrd"
      }
    }
  }
}

獨立運行

cd src
python -m observium_mcp.server

📚 詳細文檔

可用工具

示例查詢

連接成功後，你可以向 Claude 提出如下問題：

• "當前有哪些設備處於離線狀態？"
• "顯示主交換機上的溫度傳感器信息"
• "過去一週防火牆的 CPU 負載趨勢如何？"
• "是否有活動警報？"
• "核心交換機上哪些端口有錯誤？"
• "我所有 Linux 服務器的正常運行時間是多少？"

遠程訪問

如果你的 Observium 實例位於遠程服務器，你有以下幾種選擇：

選項 1：SSH 隧道

# 創建 SSH 隧道以轉發 MySQL 端口
ssh -L 3306:localhost:3306 user@observium-server

# 然後在 .env 中配置為 localhost
OBSERVIUM_DB_HOST=localhost

選項 2：在 Observium 服務器上安裝

直接在 Observium 主機上安裝 MCP 服務器，並配置 Claude 通過 SSH 進行連接。

選項 3：網絡訪問

如果 MySQL 在網絡上可訪問（出於安全考慮不建議）：

OBSERVIUM_DB_HOST=observium.example.com

安全考慮

• 數據庫憑證存儲在 .env 文件中，該文件已被添加到 .gitignore 中。
• 服務器僅執行 SELECT 查詢（只讀）。
• 為了提高安全性，考慮使用只讀的 MySQL 用戶。
• 通過 rrdtool fetch 進行的 RRD 訪問是隻讀的。

創建只讀數據庫用戶

為了進一步提高安全性，創建一個專用的只讀 MySQL 用戶：

CREATE USER 'observium_mcp'@'localhost' IDENTIFIED BY 'secure_password';
GRANT SELECT ON observium.* TO 'observium_mcp'@'localhost';
FLUSH PRIVILEGES;

故障排除

連接被拒絕

• 驗證 MySQL 是否正在運行且可訪問。
• 檢查 .env 文件中的數據庫憑證。
• 確保 MySQL 用戶具有 SELECT 權限。

沒有 RRD 數據 / 趨勢工具失敗

• 驗證 OBSERVIUM_RRD_PATH 是否指向 Observium 服務器上的正確目錄。
• 如果 MCP 在不同的機器上運行，配置 SSH 訪問：
  • 設置 OBSERVIUM_RRD_SSH_HOST 為 Observium 服務器的主機名。
  • 設置 OBSERVIUM_RRD_SSH_USER 為具有 SSH 訪問權限的用戶。
  • 確保已配置基於 SSH 密鑰的認證。
• 確保 rrdtool 已安裝在 Observium 服務器（遠程）或本地。
• 檢查 RRD 目錄的文件權限。

模塊未找到

確保你從 src 目錄運行或已安裝該包：

cd /path/to/observium-mcp/src
python -m observium_mcp.server

📄 許可證

本項目採用 MIT 許可證，詳情請見 LICENSE。

致謝

• Observium - 網絡監控平臺
• 模型上下文協議 - MCP 規範
• Anthropic - Claude 和 MCP 開發