Rigol DHO824 Oscilloscope

Rigol DHO824 MCP 服务

用于控制和查询 Rigol DHO824 示波器的 MCP（模型上下文协议）服务。

由 ai.moda 构建。

硬件要求

支持的型号

本项目仅支持 DHO804/DHO824 示波器（硬件相同）。我们建议购买 DHO804。

固件要求

重要： 使用此 MCP 服务前，必须先将 DHO804 刷写为 DHO824 固件。请使用 rigol_vendor_bin 项目刷写示波器。

支持的固件版本： 00.01.04

这是我们唯一测试并支持的固件版本。其他固件版本可能可用，但不作保证。

兼容性说明

其他 Rigol 示波器型号可能也适用于此 MCP 服务，但我们无法测试或保证其功能。使用其他型号的风险由您自行承担。

安装

推荐通过 Docker 使用此 MCP 服务，这样可以免除依赖项管理并提供隔离环境。

快速开始

从 GitHub Container Registry 拉取预构建映像：

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 中），这种方式会很方便。

环境变量

• RIGOL_RESOURCE：必需 - 用于连接示波器的 VISA 资源字符串（例如，TCPIP0::192.168.1.100::inst0::INSTR）
• RIGOL_TEMP_DIR：Docker 中必需 - 返回文件路径时使用的主机端路径。容器始终在内部写入 /tmp/rigol，并在响应中将路径转换为此值。该路径必须与 -v 挂载中的主机路径一致。在 Docker 外部，此变量用于设置临时文件（波形、截图）的目录；如果未设置，则使用系统默认临时目录。
• VISA_TIMEOUT：通信超时时间，单位为毫秒（默认值：30000）
• RIGOL_BEEPER_ENABLED：启用/禁用示波器蜂鸣器声音（默认值：false）
• RIGOL_AUTO_SCREENSHOT：每次执行 MCP 工具后自动截取屏幕，用于可视化/调试（默认值：false）。截图采用便于阅读的时间戳格式命名（例如，auto_screenshot_20251030_143045_123.png），以便按时间顺序排序。

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. 将此目录挂载为卷，并在 Docker 配置中设置 RIGOL_TEMP_DIR：

   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 中

示例：手动清理

# Remove waveform captures older than 7 days
find /tmp/rigol-data -type d -name "waveform_capture_*" -mtime +7 -exec rm -rf {} \;

# Remove screenshots older than 7 days
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  # On Windows: venv\Scripts\activate

安装软件包

# Install in editable mode for development
pip install -e .

# Or just install dependencies
pip install -r requirements.txt

添加到 MCP 客户端

完成上述设置步骤后，将本地开发用 MCP 服务添加到 MCP 客户端：

Claude Code：

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 Code 不同，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 传输

# Set resource string via environment variable
export RIGOL_RESOURCE="TCPIP0::192.168.1.100::inst0::INSTR"
python -m rigol_dho824_mcp.server

HTTP 传输

# Default HTTP server (http://127.0.0.1:8000/mcp)
python -m rigol_dho824_mcp.server --http

# Custom host and port
python -m rigol_dho824_mcp.server --http --host 0.0.0.0 --port 3000

# Custom path
python -m rigol_dho824_mcp.server --http --path /api/mcp