rigol-mcp

MCP server for controlling Rigol DS1000Z and DHO series oscilloscopes over LAN or USB. Exposes the scope as a set of tools that Claude (or any MCP client) can call to take measurements, configure the instrument, and capture screenshots — entirely through natural language.

Example: unknown signal characterisation in Claude

Unknown signal (square wave into LCR trap), wrong channel enabled, invalid timebase/voltage/trigger. Claude identifies the signal type, corrects the setup, and characterises the waveform.

Supported Hardware

Rigol DS1000Z / MSO1000Z series (8-bit):

Rigol DHO series (12-bit):

Other DHO models (DHO900/1000/4000 families) likely work with the same SCPI dialect but are not verified.

The scope connects either over your local network via Ethernet (rear panel RJ45) or over USB (rear panel USB-B device port). LAN is the default; USB is used when RIGOL_USB is set (see Configuration). USB transport has been validated on DS1000Z; DHO support has so far been validated over LAN only.

Related MCP server: SkippyMCP

Requirements

• Python 3.11+

• uv

• A Rigol DS1000Z (LAN or USB) or DHO series scope (LAN) connected to your computer

• For LAN: SCPI over TCP/IP enabled on the scope (on by default)

• For USB: a VISA driver on the scope's USB interface — either the native USBTMC driver (e.g. from Rigol UltraSigma / any NI-VISA runtime) or WinUSB via Zadig (see USB connection)

Installation

git clone https://github.com/erebusnz/rigol-mcp
cd rigol-mcp
uv sync

Scope Network Setup

On the scope, go to Utility → IO Setting → LAN and note the IP address (or assign a static one). The scope listens on port 5555 for raw SCPI commands — no additional configuration is needed.

Replace 192.168.1.123 with the IP address of your scope in all instructions below.

Verify in browser: http://192.168.1.123/DS1000Z_WelcomePage.html

Verify connectivity before using as MCP:

python -c "import pyvisa; rm = pyvisa.ResourceManager('@py'); s = rm.open_resource('TCPIP0::192.168.1.123::5555::SOCKET'); s.write_termination='\n'; s.read_termination='\n'; print(s.query('*IDN?'))"

You should see something like:

RIGOL TECHNOLOGIES,DS1054Z,DS1ZA123456789,00.04.04.SP4

Configuration

Set the scope IP for MCP via environment variable:

export RIGOL_IP=192.168.1.123

Or create a .env file (copy from .env.example):

RIGOL_IP=192.168.1.123

Optional:

USB connection

Set RIGOL_USB=1 to connect over USB instead of LAN. The server looks for a Rigol scope on USB (vendor ID 0x1AB1) and connects to it. If more than one scope is connected, set RIGOL_USB_SERIAL to choose which one by serial number.

RIGOL_USB=1
# RIGOL_USB_SERIAL=DS1ZA000000000   # only needed if more than one scope is on USB

Windows USB instructions

The scope's USB interface needs a VISA-compatible driver. The server auto-detects whichever you have installed — pick one:

Option A — install the WinUSB driver with Zadig. The server talks to the scope through the bundled pure-Python pyvisa-py (@py) backend (pyusb + libusb); no extra Rigol software needed. Do this once per scope:

1. Connect the scope over USB and power it on.

2. Download and run Zadig.

3. Choose Options → List All Devices.

4. Select "DS1000Z Series" in the device dropdown.

5. Set the target driver to WinUSB and click Install Driver (or Replace Driver).

6. Wait for "The driver was installed successfully", then set RIGOL_USB=1.

Option B — install Rigol UltraSigma, which bundles the driver. UltraSigma installs the standard "USB Test and Measurement Device" (USBTMC) driver. Once it's installed, the server reaches the scope through the NI-VISA (@ivi) backend — nothing else to configure.

Note: the two drivers are mutually exclusive on a given USB interface. Installing WinUSB (Option A) means UltraSigma can no longer see the scope over USB until you revert the driver in Device Manager, and vice versa. LAN access is unaffected either way.

Linux / macOS USB

Works without needing drivers using the pyvisa-py (@py) backend.

• macOS: typically works as-is once RIGOL_USB=1 is set; no driver to install.

• Linux: give your user permission to claim the device with a udev rule, then replug it:

  # /etc/udev/rules.d/60-rigol.rules
  SUBSYSTEM=="usb", ATTRS{idVendor}=="1ab1", MODE="0660", GROUP="plugdev"

  sudo udevadm control --reload-rules && sudo udevadm trigger

  (Make sure your user is in the plugdev group: sudo usermod -aG plugdev $USER, then log out and back in.)

  If the kernel's usbtmc module has already claimed the scope, unbind or blacklist it so libusb can take the interface — pyvisa-py does not detach it automatically.

USB is currently hardware-tested on Windows only; Linux/macOS use the standard libusb setup above.

Claude Desktop / Claude Code Setup

Add to your .mcp.json (or Claude Desktop MCP config):

{
  "mcpServers": {
    "rigol": {
      "command": "uv",
      "args": ["run", "rigol-mcp"],
      "cwd": "/path/to/rigol-mcp",
      "env": {
        "RIGOL_IP": "192.168.1.123"
      }
    }
  }
}

For USB, replace the RIGOL_IP entry in env with "RIGOL_USB": "1" (see USB connection).

Tools

Identification & State

Acquisition Control

Configuration

Measurement

Cursors

Utility

Example Prompts

Basic measurement session:

"Connect to the scope, check what's configured, then measure the frequency and Vpp on channel 1."

Signal characterisation:

"Stop the scope, download the waveform from channel 2, and tell me the rise time, overshoot percentage, and estimated fundamental frequency."

Setup from scratch:

"Set channel 1 to 2V/div DC coupling with a 10x probe, set the timebase to 1ms/div, trigger on channel 1 rising edge at 1V, then run and take a screenshot."

Cursor measurement:

"Put manual cursors on the first rising edge of the signal on channel 1 — cursor A at the 10% level and cursor B at the 90% level — and read the rise time from the delta."

Transient / ringing characterisation:

"There's a damped oscillation on channel 1 after a step edge. Stop the scope, measure Vpp, Vmax, Vmin, and Vrms, then estimate the ring frequency and how many cycles it takes to decay."

Iterative debugging:

"I'm verifying the gain of an amplifier. Channel 1 is the input, channel 2 is the output. The expected gain is 20 dB. Figure out whether it's within spec."

Unknown signal characterisation:

"There's an unfamiliar signal on channel 1. I don't know its frequency, amplitude, or shape. Keep adjusting the timebase and vertical scale until you have a stable, well-framed view of at least two full cycles, then give me a complete characterisation of what you see."

Architecture

Claude / MCP client
        │  MCP protocol (stdio)
rigol_mcp.server      ← tool definitions, request routing
        │  Python function calls
rigol_mcp.scope       ← VISA connection, SCPI command helpers
        │  SCPI over TCP/IP (port 5555) or USBTMC
Rigol DS1000Z         ← 192.168.1.123  /  USB

The VISA connection is cached across tool calls (one connection per server session) and reconnects automatically on communication errors.

SCPI Transport

By default the server connects using raw socket VISA (TCPIP0::<ip>::5555::SOCKET), not VXI-11. This avoids the NI-VISA dependency and works with the pure-Python pyvisa-py backend. It also eliminates the VXI-11 handshake overhead, making individual commands faster.

When RIGOL_USB is set, the server instead connects over USBTMC (USB0::0x1AB1::<model>::<serial>::INSTR), discovering the scope automatically. It auto-selects whichever VISA backend can see the scope:

• @py (pyvisa-py + pyusb + bundled libusb) — for a USB interface bound to WinUSB (no NI-VISA needed).

• @ivi (NI-VISA / IVI VISA) — for the native USBTMC driver (e.g. installed with Rigol UltraSigma).

The two backends frame USBTMC reads differently, so block reads (waveform/screenshot) are read by exact byte count on @py and via native message reads (read_raw) on @ivi. Transport and backend selection live in rigol_mcp.scope.get_scope / _open_usb_scope.

Testing

Unit tests are fully offline — the VISA layer is faked, so no instrument is required.

uv run --extra test pytest      # or: uv sync --extra test && uv run pytest

Limitations

• USB driver setup is platform-specific: Windows needs WinUSB (via Zadig) or NI-VISA/UltraSigma; Linux needs libusb access (a udev rule) or NI-VISA; macOS typically works through libusb with no setup. The server auto-detects the backend — see USB connection. LAN needs no driver setup on any platform.

• No support for math channels, digital channels (MSO), or protocol decode in the current tools yet — use send_raw for those

• Waveform download uses NORMAL mode (screen buffer — up to 1200 points on DS1000Z, 1000 on DHO); full memory depth (RAW mode, up to 56M on DS1000Z / 50M on DHO) is not yet implemented

License

MIT — see LICENSE.