rigol-oscilloscope-mcp

一个 MCP（Model Context Protocol）服务器，让 LLM（Claude、Codex 等）通过 SCPI（LAN / USB）驱动 RIGOL 示波器——连接、配置通道/时基/触发、测量、捕获波形和截图、解码串行协议、运行宿主侧 FFT 分析，以及控制内置 AFG，全部通过带四级安全策略的语义化工具实现。已在真实 RIGOL MHO98 上验证；其他 RIGOL 型号通过机型配置文件尽力支持。文档目前为日文。

从 LLM 操作 RIGOL 示波器的 MCP 服务器。

LLM（Claude / Codex 等）将「用 x10 探头让 1kHz 3V 的波形可见」「把当前波形截图保存」等自然语言指令转换为 MCP Tool 调用，本服务器通过 SCPI（LAN / USB）控制设备。不使用 GUI 自动操作。

• 已在 RIGOL MHO98 上完成实机验证（→ docs/verification/mho98-mvp.md）

• 其他 RIGOL 机型通过机型配置文件进行尽力而为（best-effort）支持（未知机型使用 generic 配置文件运行，并明确说明这一点）

• 非 RIGOL 厂商不在支持范围内（连接时返回警告但不拒绝）

特点

• 基于会话的连接 — 连接目标基本由用户在会话中指定（connect(address="...")）。环境变量默认值只是可选的回退方案

• 26 个 MCP Tool — 连接 / 识别 / 状态获取 / 测量 / 波形 / 分析（统计・FFT）/ 截图 / 通道・时基・触发设置 / Run・Stop・Single・Autoset / 串行解码设置・结果获取 / 信号发生器（AFG）设置・状态获取・输出控制（输出 ON 带确认流程）。不让 LLM 编写 SCPI 字符串，只公开语义化 Tool

• 4 级安全策略 + confirm 令牌 — 将所有操作分为 READ_ONLY / SAFE_WRITE / RESTRICTED_WRITE / DANGEROUS_WRITE。50Ω 输入和 Auto Setup 必须经过不依赖宿主 UI 的两步确认（confirm 令牌）

• 截图保存 — 以 png / jpg / bmp / webp 格式保存到指定路径，并将图像本身返回给 LLM（写入位置受允许路径限制）

• 机型配置文件 — 通过随附的 YAML 声明 SCPI 方言・功能有无・参数范围，按 型号完全匹配 → 系列 → 通用 RIGOL 三层解析

• 返回 requested / applied 两个值 — 设备是否对设定值进行吸附（snap）取决于机型，因此同时返回请求值和回读（read-back）值

• 审计日志 — 将写入操作连同 Before / Action / After 记录为 JSONL

Related MCP server: Rigol DHO824 MCP Server

安装・启动

以从 GitHub 仓库通过 uvx 启动为标准方式。

uvx --from git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0 rigol-oscilloscope-mcp

默认将版本固定到标签（@v0.1.0）。要使用最新开发版（main）时，请去掉 @v0.1.0。

Claude Code — 插件（推荐）

本仓库兼作 Claude 插件，除 MCP 服务器外，还会同时安装测量工作流技能（按信号类型推荐设置・UART/未知信号的测量步骤・安全提示词）。先添加市场（marketplace）再安装（@ 之后是市场名称）：

/plugin marketplace add zinntikumugai/rigol-oscilloscope-mcp
/plugin install rigol-oscilloscope@rigol-oscilloscope-mcp

Claude Code（.mcp.json 或 claude mcp add）

{
  "mcpServers": {
    "rigol-oscilloscope": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0", "rigol-oscilloscope-mcp"],
      "env": { "RIGOL_MCP_SCREENSHOT_DIR": "~/scope-captures" }
    }
  }
}

Codex — 插件

同时附带 Codex 插件（.codex-plugin/ + 市场定义），可一次性安装 MCP 服务器和测量工作流技能。

codex plugin marketplace add zinntikumugai/rigol-oscilloscope-mcp
codex plugin install rigol-oscilloscope

（不使用插件时，如果只要技能，将 skills/measurement-workflows 复制到 ~/.agents/skills/ 也会被识别。如果只要 MCP 服务器，以下 config.toml 设置就足够了）

Codex（~/.codex/config.toml）

[mcp_servers.rigol-oscilloscope]
command = "uvx"
args = ["--from", "git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0", "rigol-oscilloscope-mcp"]

[mcp_servers.rigol-oscilloscope.env]
RIGOL_MCP_SCREENSHOT_DIR = "~/scope-captures"

从本地 clone 启动时

将仓库 clone 到本地使用开发版时，用 uv run --directory 启动。

{
  "mcpServers": {
    "rigol-oscilloscope": {
      "command": "/path/to/uv",
      "args": ["run", "--directory", "/path/to/rigol-oscilloscope-mcp", "rigol-oscilloscope-mcp"],
      "env": { "PYTHONDONTWRITEBYTECODE": "1" }
    }
  }
}

• 当 GUI 宿主（桌面应用）的 PATH 中没有 uv 时，command 用绝对路径书写。路径用 which uv（mise 管理时用 mise which uv）确认

• 明确设置 PYTHONDONTWRITEBYTECODE=1。从项目外启动时 mise.toml 的 [env] 不生效，因此用于防止 __pycache__ 被写入 clone 内

• 截图的默认保存位置是启动服务器的执行目录，而不是 --directory 移动到的位置。要固定时请指定 RIGOL_MCP_SCREENSHOT_DIR

• 向 path 传入相对路径时也以该默认保存位置为基准。无法保存到默认保存位置・RIGOL_MCP_ALLOWED_DIRS・临时目录之外（会被拒绝）

设置（环境变量）

所有设置都可以通过环境变量指定（也可以任意使用 TOML 配置文件）。优先级为 Tool 参数（会话中的用户指示）> 环境变量 > 配置文件 > 内置默认值。

详见 docs/Requirements.md 第 9 章。

没有实机时试用

加上 RIGOL_MCP_FAKE=1 启动时，会连接到内置的 FakeScope 而不是实机。无需准备示波器即可确认宿主侧的 MCP 设置和会话流程。

RIGOL_MCP_FAKE=1 uvx --from git+https://github.com/zinntikumugai/rigol-oscilloscope-mcp@v0.1.0 rigol-oscilloscope-mcp

开发

Python 版本用 mise 管理，依赖和虚拟环境用 uv 管理。

mise install          # Python + uv
uv sync               # 依存の解決
uv run pytest         # ユニットテスト(実機不要)
uv run rigol-oscilloscope-mcp   # stdioで起動

实机测试仅在通过环境变量传入连接目标时执行（未设置时自动跳过）。绝对不要把实机的 IP 地址写进仓库（tests/test_ip_guard.py 会机械地检查）。

# read-only スイート(機器の設定を変更しない)
RIGOL_TEST_ADDRESS=<あなたのオシロのIP> uv run pytest -m device

# write スイート(設定変更 → read-back → 必ず復元)。二重ゲート
RIGOL_TEST_ADDRESS=<あなたのオシロのIP> RIGOL_TEST_ALLOW_WRITE=1 uv run pytest -m device_write

在 <您的示波器 IP> 中填入您自己设备的地址（需要示例时，请使用为文档保留的 192.0.2.x（TEST-NET-1））。

故障排除

安全注意事项

包括 MHO98 在内的许多 RIGOL 示波器都是非隔离的（各输入的 GND 与机箱・USB 等的 GND 共通，测量类别为 Category I）。本服务器可防止危险的设置变更，但不保证电气安全本身。

• 探头的连接位置・Ground Clip 的连接位置・DUT 的实际电压・探头耐压・绝缘状态，无法通过 MCP 确认

• **商用电源（100V AC、插座、一次侧、AC mains）的测量不在支持范围内。**不自动执行使用普通无源探头的测量步骤。前提是人类确认使用差分・隔离探头

• Firmware Update / Calibration / Factory Service 操作 / 网络设置变更不在支持范围内

详见 docs/Requirements.md 第 6 章（安全需求）。

confirm 流程的信任模型： 两步确认（confirm 令牌）是防止 LLM 误操作・过早下结论的机制，并非对恶意 MCP 宿主的防御（因为令牌会返回给同一个调用方，宿主自身若有恶意，只需调用两次即可通过）。物理安全只能由管理「配线了什么」的人类来保障。另外，enable_afg 的令牌还绑定到发行时的 AFG 设置，发行后若更改设置（振幅等），令牌将失效。

免责声明： 本软件按无担保方式提供（LICENSE）。因使用本软件导致的测量仪器・被测物（DUT）・周边设备的损坏、测量结果的错误，以及由此产生的任何损害，作者均不承担责任。

许可证

MIT License — Copyright (c) 2026 zinntikumugai

文档

docs/README.md 汇总了文档列表和阅读顺序。

• docs/Requirements.md — 需求定义书（规范）

• docs/tools.md — MCP Tool 目录

• docs/device-profiles.md — 机型配置文件规格

• docs/verification/ — 实机验证记录

• docs/roadmap.md — 今后的支持计划