rigol-oscilloscope-mcp

LLM(Claude, Codex 등)이 SCPI(LAN / USB)를 통해 RIGOL 오실로스코프를 구동할 수 있게 해주는 MCP(Model Context Protocol) 서버 — 연결, 채널/타임베이스/트리거 구성, 측정, 파형 및 스크린샷 캡처, 직렬 프로토콜 디코딩, 호스트 측 FFT 분석, 내장 AFG 제어를 모두 4단계 안전 정책을 갖춘 의미론적 도구로 제공합니다. 실제 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 두 값 반환 — 장비가 설정값을 스냅(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/미지 신호 측정 절차·안전 프롬프트)이 함께 설치됩니다. 마켓플레이스를 추가한 다음 설치합니다(@ 이후는 마켓플레이스 이름):

/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, 콘센트, 1차측, AC mains) 측정은 대상 외입니다.**일반 패시브 프로브에 의한 측정 절차를 자동 실행하지 않습니다. 차동·절연 프로브 사용을 인간이 확인하는 것을 전제로 합니다

• Firmware Update / Calibration / Factory Service 작업 / 네트워크 설정 변경은 대상 외입니다

자세한 내용은 docs/Requirements.md 6장(안전 요구사항)을 참조하세요.

confirm 플로우의 신뢰 모델: 2단계 확인(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 — 향후 대응 예정