rigol-oscilloscope-mcp

MCP (Model Context Protocol) サーバーは、LLM (Claude / Codex など) が SCPI (LAN / USB) 経由で RIGOL オシロスコープを操作できるようにします。接続、チャンネル / タイムベース / トリガの設定、測定、波形とスクリーンショットの取得、シリアルプロトコルのデコード、ホスト側 FFT 解析、内蔵 AFG の制御を、4クラスの安全ポリシーを備えた意味的Toolで行えます。実機の RIGOL MHO98 で検証済み。他の RIGOL モデルは機種プロファイルによるベストエフォートで動作します。ドキュメントは現在日本語です。

RIGOL製オシロスコープを LLMから操作する MCPサーバー。

「x10プローブで1kHz 3Vの波形を見えるようにして」「今の波形をスクショして保存して」といった自然言語の指示を、 LLM(Claude / Codex 等)がMCP Tool呼び出しへ変換し、本サーバーがSCPI(LAN / USB)で機器を制御する。 GUI自動操作は使わない。

• RIGOL MHO98 で実機検証済み(→ docs/verification/mho98-mvp.md)

• 他のRIGOL機種は機種プロファイルによるベストエフォート対応(未知の機種は generic プロファイルで動作し、その旨を明示する)

• RIGOL以外のベンダーは対象外(接続時に警告を返すが拒否はしない)

特徴

• 会話ベースの接続 — 接続先はユーザーが会話で指示するのが基本(connect(address="..."))。環境変数のデフォルトは任意のフォールバック

• 26個のMCP Tool — 接続 / 識別 / 状態取得 / 測定 / 波形 / 解析(統計・FFT)/ スクリーンショット / チャンネル・タイムベース・トリガ設定 / Run・Stop・Single・Autoset / シリアルデコード設定・結果取得 / 信号発生(AFG)設定・状態取得・出力制御(出力ONは確認フロー付き)。SCPI文字列をLLMに書かせず、意味的Toolのみを公開する

• 4クラスの安全ポリシー + confirmトークン — 全操作を READ_ONLY / SAFE_WRITE / RESTRICTED_WRITE / DANGEROUS_WRITE に分類。50Ω入力やAuto SetupはホストUI非依存の2段階確認(confirmトークン)を必須とする

• スクリーンショット保存 — png / jpg / bmp / webp で指定パスへ保存し、画像そのものもLLMへ返す(書き込み先は許可ルートで制限)

• 機種プロファイル — SCPI方言・機能有無・パラメータ範囲を同梱YAMLで宣言し、モデル完全一致 → ファミリ → 汎用RIGOL の3層で解決する

• requested / applied の両値返却 — 機器が設定値をスナップするかは機種依存のため、要求値と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/未知信号の測定手順・安全プロンプト)が同時に導入される。 マーケットプレイスを追加してからインストールする(@ 以降はマーケットプレイス名):

/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" }
    }
  }
}

• command は、GUIホスト(デスクトップアプリ)のPATHに uv が無い場合に絶対パスで書く。パスは 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で起動

実機テストは接続先を環境変数で渡したときだけ実行される(未設定なら自動でskip)。 実機の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フローの信頼モデル: 2段階確認(confirmトークン)は、LLMの誤操作・早とちりを防ぐための仕組みであり、悪意あるMCPホストへの防御ではない(トークンは同じ呼び出し元へ返るため、ホスト自身が悪意を持てば2回呼ぶだけで通過できる)。物理的な安全は「何が配線されているか」を管理する人間にのみ担保できる。なお 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 — 今後の対応予定