Rigol Dho824 MCP

🚀 普源精電DHO824 MCP服務器

這是一個用於控制和查詢普源精電DHO824示波器的MCP（模型上下文協議）服務器。藉助該服務器，用戶可以方便地對示波器進行操作和數據查詢。

由 ai.moda 構建。

🚀 快速開始

硬件要求

支持的型號

本項目僅支持DHO804/DHO824示波器（硬件相同）。我們建議購買DHO804。

固件要求

⚠️ 重要提示

在使用此MCP服務器之前，必須將DHO804刷入DHO824固件。請使用 rigol_vendor_bin 項目來刷寫您的示波器。

支持的固件版本：00.01.04

這是我們測試和支持的唯一固件版本。其他固件版本可能可以使用，但不保證其功能正常。

兼容性說明

其他普源精電示波器型號可能與此MCP服務器兼容，但我們無法對其進行測試或保證其功能。使用其他型號時請自行承擔風險。

安裝

使用此MCP服務器的推薦方式是通過Docker，它可以消除依賴管理問題並提供隔離環境。

快速開始

從GitHub容器註冊表拉取預構建的鏡像：

docker pull ghcr.io/aimoda/rigol-dho824-mcp:latest

使用Docker環境變量

⚠️ 重要提示

您必須提供 RIGOL_RESOURCE 環境變量，並設置為您示波器的IP地址（例如，TCPIP0::192.168.1.100::inst0::INSTR）。

您可以通過以下兩種方式使用環境變量配置Docker容器：

1. 硬編碼值（以下示例所示）：-e RIGOL_RESOURCE="TCPIP0::192.168.1.100::inst0::INSTR"
2. 從主機傳遞（推薦）：-e RIGOL_RESOURCE（不指定 =value）

當您使用 -e VARIABLE_NAME 而不指定值時，Docker會自動從您的主機環境中傳遞該變量。如果您已經在shell中設置了環境變量（例如，在 ~/.bashrc 或 ~/.zshrc 中），這將非常有用。

環境變量

MCP客戶端配置

{
  "mcpServers": {
    "rigol-dho824": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/tmp/rigol-data:/tmp/rigol",
        "-e",
        "RIGOL_RESOURCE",
        "-e",
        "VISA_TIMEOUT",
        "-e",
        "RIGOL_BEEPER_ENABLED",
        "-e",
        "RIGOL_AUTO_SCREENSHOT",
        "-e",
        "RIGOL_TEMP_DIR",
        "ghcr.io/aimoda/rigol-dho824-mcp:latest"
      ],
      "env": {
        "RIGOL_RESOURCE": "TCPIP0::192.168.1.100::inst0::INSTR",
        "VISA_TIMEOUT": "30000",
        "RIGOL_BEEPER_ENABLED": "false",
        "RIGOL_AUTO_SCREENSHOT": "false",
        "RIGOL_TEMP_DIR": "/tmp/rigol-data"
      }
    }
  }
}

claude mcp add --scope local rigol-dho824 -- \
  docker run -i --rm \
  -v /tmp/rigol-data:/tmp/rigol \
  -e RIGOL_RESOURCE="TCPIP0::192.168.1.100::inst0::INSTR" \
  -e VISA_TIMEOUT=30000 \
  -e RIGOL_BEEPER_ENABLED=false \
  -e RIGOL_AUTO_SCREENSHOT=false \
  -e RIGOL_TEMP_DIR=/tmp/rigol-data \
  ghcr.io/aimoda/rigol-dho824-mcp:latest

codex mcp add rigol-dho824 -- \
  docker run -i --rm \
  -v /tmp/rigol-data:/tmp/rigol \
  -e RIGOL_RESOURCE="TCPIP0::192.168.1.100::inst0::INSTR" \
  -e VISA_TIMEOUT=30000 \
  -e RIGOL_BEEPER_ENABLED=false \
  -e RIGOL_AUTO_SCREENSHOT=false \
  -e RIGOL_TEMP_DIR=/tmp/rigol-data \
  ghcr.io/aimoda/rigol-dho824-mcp:latest

⚠️ 重要提示

將服務器添加到您的MCP客戶端後，請重啟客戶端以加載MCP服務器。服務器將在所有返回的文件路徑中將容器路徑（/tmp/rigol/*）轉換為主機路徑（/tmp/rigol-data/*）。

首次提示

在您的MCP客戶端中輸入以下提示以驗證您的設置：

Capture a waveform from channel 1 of my oscilloscope

您的MCP客戶端應該連接到示波器並捕獲波形數據。

在Docker中訪問臨時文件

容器內部將臨時文件（波形捕獲、截圖）寫入 /tmp/rigol。要從您的主機訪問這些文件：

1. 在您的主機上創建一個目錄 用於存儲臨時文件：

   mkdir -p /tmp/rigol-data
   

2. 將此目錄作為卷掛載 並 設置 RIGOL_TEMP_DIR 在您的Docker配置中：

   docker run -i --rm \
     -v /tmp/rigol-data:/tmp/rigol \
     -e RIGOL_TEMP_DIR=/tmp/rigol-data \
     ...
   

服務器會自動將所有返回的文件路徑從容器路徑（/tmp/rigol/*）轉換為主機路徑（/tmp/rigol-data/*），因此您可以直接在工具響應中顯示的路徑訪問文件。

⚠️ 重要提示

• 主機目錄（示例中的 /tmp/rigol-data）必須在啟動服務器之前存在
• RIGOL_TEMP_DIR 必須與 -v 掛載中的主機端路徑匹配
• 臨時文件不會自動清理
• 您需要手動清理舊的波形和截圖文件
• 文件將按子目錄組織，如 waveform_capture_<timestamp>/ 用於波形，screenshot_<timestamp>.png 用於截圖

示例：手動清理

# 刪除7天前的波形捕獲
find /tmp/rigol-data -type d -name "waveform_capture_*" -mtime +7 -exec rm -rf {} \;

# 刪除7天前的截圖
find /tmp/rigol-data -type f -name "screenshot_*.png" -mtime +7 -delete

故障排除

容器立即退出

• 確保您使用了 -i 標誌（交互模式）
• 驗證 RIGOL_RESOURCE 是否設置正確

無法連接到示波器

• 驗證示波器的IP地址和網絡連接（ping <ip-address>）
• 檢查示波器的遠程控制設置是否已啟用

環境變量不起作用

• 確保您在Docker參數數組中使用了 -e VARIABLE_NAME
• 在 .mcp.json 的 env 字段中設置實際值

本地構建

要自己構建Docker鏡像：

docker build -t rigol-dho824-mcp:local .

然後在您的配置中使用 rigol-dho824-mcp:local 作為鏡像名稱。

🔧 技術細節

開發設置

對於本地開發和貢獻，您可以在Python虛擬環境中安裝MCP服務器。

創建並激活虛擬環境

python3 -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

安裝包

# 以可編輯模式安裝以進行開發
pip install -e .

# 或者僅安裝依賴項
pip install -r requirements.txt

添加到MCP客戶端

完成上述設置步驟後，將本地開發的MCP服務器添加到您的MCP客戶端：

Claude代碼：

claude mcp add --scope local rigol-dho824 -- <path-to-this-repo>/venv/bin/rigol-dho824-mcp

Codex CLI：

codex mcp add \
  --env RIGOL_RESOURCE="TCPIP0::192.168.1.100::inst0::INSTR" \
  --env VISA_TIMEOUT="30000" \
  --env RIGOL_BEEPER_ENABLED="false" \
  --env RIGOL_AUTO_SCREENSHOT="false" \
  rigol-dho824 -- <path-to-this-repo>/venv/bin/rigol-dho824-mcp

替換：

• <path-to-this-repo> 為該倉庫的實際路徑
• 192.168.1.100 為您示波器的IP地址

⚠️ 重要提示

與Claude代碼不同，Codex需要通過 --env 標誌顯式設置環境變量（在服務器名稱之前），因為它在清理後的環境中運行MCP服務器。

開發腳本

scripts/ 目錄包含用於開發的實用工具：

• convert_png_to_webp.sh - 將PNG幀序列轉換為動畫WebP（例如，./scripts/convert_png_to_webp.sh "~/screenshots/*.png" output.webp）

開發配置

服務器可以使用環境變量進行配置。從示例創建一個 .env 文件：

cp .env.example .env

然後編輯 .env 以設置您的配置：

• RIGOL_RESOURCE：示波器的VISA資源字符串（必需）
  • 示例：TCPIP0::192.168.1.100::inst0::INSTR
• VISA_TIMEOUT：通信超時時間（毫秒）（默認值：5000）

運行服務器（開發）

對於本地開發和測試，您可以直接使用Python運行服務器：

STDIO傳輸

# 通過環境變量設置資源字符串
export RIGOL_RESOURCE="TCPIP0::192.168.1.100::inst0::INSTR"
python -m rigol_dho824_mcp.server

HTTP傳輸

# 默認HTTP服務器（http://127.0.0.1:8000/mcp）
python -m rigol_dho824_mcp.server --http

# 自定義主機和端口
python -m rigol_dho824_mcp.server --http --host 0.0.0.0 --port 3000

# 自定義路徑
python -m rigol_dho824_mcp.server --http --path /api/mcp