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