rigol-mcp
The server exposes MCP stdio tools to identify, configure, inspect, capture, and analyze a supported Rigol oscilloscope (primarily DHO814) over LAN/TCPIP, with file-backed captures and scriptable SCPI access.
Identity/status:
idn,get_capabilities,get_scope_state,check_errorConfiguration:
set_channel,set_timebase,set_trigger,set_cursors,autoscaleAcquisition control:
run,stop,singleMeasurements:
measure,measure_between,get_cursor_valuesWaveform capture and analysis:
get_waveform,download_waveform, plus README workflows such asacquire_and_capture,capture_waveforms,analyze_waveform, timing capture, and PWM envelope analysisSCPI access: browse the pinned DHO814 catalog with
scpi_catalog, execute catalog commands withscpi_execute, and optionally enable raw SCPI viaRIGOL_ENABLE_SEND_RAWFiles and images: save screenshots with
screenshot, generate waveform/CSV/JSON data underRIGOL_DATA_DIR, and read bounded file excerpts withread_capturePersistence/workflow: save and restore scope setups, retain captures/screenshots in a mounted data volume, and follow no-retry/readback guidance for state-changing operations
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rigol-mcp Measure the peak-to-peak voltage on channel 2"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
rigol-mcp
A standards-based Model Context Protocol server for controlling a Rigol oscilloscope over LAN/TCPIP. Any MCP client supporting stdio can discover its tools, configure the instrument, take measurements and retrieve captures. No particular agent or client is required.

Scope Support
The programming reference is Rigol's DHO800/DHO900 guide. The DHO814 belongs to the DHO800 series and is the primary tested target. Its model-filtered command catalog and streamed memory downloads are enabled specifically for DHO814; this is not a claim of complete support for every model covered by the guide.
Existing DS1000Z/MSO1000Z and DHO924S convenience-tool support is retained separately. Other families are not verified. See DHO814 support for reference provenance, coverage, model exclusions and hardware verification.
Related MCP server: rigol-dho-mcp
Requirements
A supported scope reachable over Ethernet on TCP port 5555.
An MCP client that can launch a stdio server.
Docker, or Apple's
containerruntime on Apple silicon, installed and running with its CLI available to the MCP client.
The server runs only in containers. No host Python, uv, or native installation is required.
Installation
git clone https://github.com/gloveboxes/rigol-mcp
cd rigol-mcpDocker
Build the lightweight Alpine image and pass the scope address at runtime:
docker build -t rigol-mcp:local .
docker run --rm -i \
-e RIGOL_IP=192.168.1.123 \
--mount type=volume,src=rigol-mcp-data,dst=/data \
rigol-mcp:localThe MCP client normally launches this command. Use -i, not -t; no ports need publishing. See Docker setup for client configuration, persistent storage, hardened launch options and the stdio-versus-HTTP tradeoff.
Apple Silicon Container
On Apple silicon, Apple Container can build the same image and run it without Docker Desktop. Apple's supported requirements are an Apple silicon Mac and macOS 26; older macOS versions are not supported.
Install the Container formula using Homebrew, then verify the CLI:
brew install container
container --versionEnsure Homebrew's bin directory (normally /opt/homebrew/bin on Apple silicon) is on the PATH used by your terminal and MCP client. Restart VS Code if it cannot find container after installation.
Start the service and build the MCP image from this repository's root:
container system start
container build -t rigol-mcp:local .Initialize the Apple capture volume once so the non-root server can write to it:
container run --rm --progress none --user 0 \
--mount type=volume,source=rigol-mcp-data,target=/data \
--entrypoint sh rigol-mcp:local -c \
'mkdir -p /data/captures /data/screenshots && chown 10001:10001 /data /data/captures /data/screenshots'Then launch the server:
container run --rm -i --read-only --progress none \
--tmpfs /tmp --cap-drop ALL \
-e RIGOL_IP=192.168.1.123 \
--mount type=volume,source=rigol-mcp-data,target=/data \
rigol-mcp:localApple Container keeps images and volumes separately from Docker. See the full Apple Container setup for VS Code configuration, storage and networking details.
Configuration
Find the scope's address in its LAN settings and replace 192.168.1.123 in the examples. Ensure TCP port 5555 is reachable. LAN/TCPIP is the only supported instrument transport.
Pass RIGOL_IP with Docker's -e option, as shown above, or set it in the MCP client configuration below. No environment file is required and no IP address is baked into the image. Docker's --env-file remains an optional alternative for managing runtime variables.
Variable | Container Default | Purpose |
| (required) | Scope IP address |
| (unset) | Set to |
|
| Directory for saved PNG screenshots |
|
| Directory for waveform CSV downloads and binary/large SCPI responses |
Docker stores captures and screenshots under /data; mount it to retain files after the container exits. Returned paths are container paths, not host paths.
MCP Client Setup
Choose one runtime and place its configuration in .vscode/mcp.json. Do not add both entries for the same scope.
Docker
{
"servers": {
"rigol-scope": {
"type": "stdio",
"command": "docker",
"args": [
"run", "--rm", "-i", "--read-only",
"--tmpfs", "/tmp:rw,noexec,nosuid,size=16m",
"--cap-drop=ALL", "--security-opt=no-new-privileges",
"-e", "RIGOL_IP", "-e", "RIGOL_ENABLE_SEND_RAW",
"--mount", "type=volume,src=rigol-mcp-data,dst=/data",
"rigol-mcp:local"
],
"env": {
"RIGOL_IP": "192.168.1.43",
"RIGOL_ENABLE_SEND_RAW": "0"
}
}
}
}Apple Container
{
"servers": {
"rigol-scope": {
"type": "stdio",
"command": "container",
"args": [
"run", "--rm", "-i", "--read-only", "--progress", "none",
"--tmpfs", "/tmp",
"--cap-drop", "ALL",
"-e", "RIGOL_IP", "-e", "RIGOL_ENABLE_SEND_RAW",
"--mount", "type=volume,source=rigol-mcp-data,target=/data",
"rigol-mcp:local"
],
"env": {
"RIGOL_IP": "192.168.1.43",
"RIGOL_ENABLE_SEND_RAW": "0"
}
}
}
}Edit env.RIGOL_IP for your scope. The included .vscode/mcp.json contains both working definitions for repository development, but a normal client setup should use only the selected runtime. Clients that use an mcpServers section can adapt the chosen process entry to their configuration format. See Docker MCP client configuration or Apple Container setup for prerequisites.
Discover Before Acting
MCP tool discovery supplies descriptions and input schemas. Measurement lists and command signatures do not need to be copied from this README.
Call
inspect_scopefor identity, capabilities and current channel, timebase and trigger settings in one sequential operation. Checkcompleteanderrorsbefore acting. Failed stages stop inspection without retrying; completed results are retained. Setverify_hardware=trueto enable channel/grid count probes that read and clear SCPI errors; the default isfalse.Use
idn,get_capabilitiesorget_scope_statefor targeted queries.Use the advertised convenience tools for common tasks. For other DHO814 operations, search
scpi_catalog, request one command's details, then usescpi_execute.
get_capabilities labels each fact in an evidence map as hardware-verified, documented, or unverified. By default it checks DHO800/900 channel and grid counts against the scope, reporting model mismatches. Other facts still rely on model definitions; measurement lists do not establish measurement accuracy. Documented facts come from a locally reviewed, versioned dataset with publication, section and page citations. CI checks its consistency with the pinned command catalog; no reference material is fetched or trusted automatically at runtime. Use verify_hardware=false to skip these extra queries. See capability evidence for limitations. scpi_catalog comes from the bundled programming-guide reference, not from an API downloaded from the scope.
Example request to an agent:
Identify the scope, check its capabilities and current settings, then measure frequency and peak-to-peak voltage on channel 1.
Semantic Workflows
Common DHO814 operations have validated semantic tools for acquisition, measurement statistics, meter, serial/CAN decode, protocol triggers, math, reference, mask testing, waveform search, and frame recording/replay. analyze_waveform returns compact statistics, frequency and FFT results without saving the raw samples. To retain raw data, use capture_waveforms, acquire_and_capture, or get_waveform with raw_data=true. Its rate metadata distinguishes the hardware acquisition rate from the displayed point rate, identifies interpolated display points, and caps the analysis Nyquist limit at the lower of those rates. DHO math traces (MATH1 through MATH4) are accepted by the screen waveform and aligned capture tools.
Decoder configuration accepts protocol-specific voltage thresholds through settings.thresholds_v, for example {"TX": 1.65} or {"SCL": 1.65, "SDA": 1.65}. DHO814 NORM waveform transfer can return no data while a decoder overlay is displayed; disable that bus display or use a RAW download.
configure_math supports FFT and filter settings. Filter cutoff readback is compared with the requested value and reports a warning when acquisition limits force the scope to clamp it. analyze_pwm_envelope extracts PWM carrier stability, duty and reconstructed average-voltage envelopes, modulation frequency, and phase between two aligned channels. Settled rail estimates exclude edge overshoot from the reconstructed voltage, while generic analysis reports robust swing, overshoot, and undershoot separately. PWM results include edge, period, and envelope sample counts with a confidence level. Reconstruction does not turn an unfiltered PWM pin into an analog output.
acquire_and_capture arms a single acquisition, waits for completion with a bounded timeout, and saves aligned channel traces. It stops acquisition on timeout. For an already stopped record, use capture_waveforms. Search event results are paginated; mask counters and measurement statistics return structured numeric validity.
Use save_scope_setup before temporary reconfiguration. restore_scope_setup only accepts generated files, requires a single-use confirmation, and is not retried. New snapshots include a represented-state sidecar; restoration reads the scope back and reports any channel, timebase, or trigger mismatch. Recording and replay controls are also not retried after uncertain outcomes.
For timing work, use configure_timing_capture with caller-defined signal labels, voltage domains and trigger criteria. It can derive a useful time scale from signal frequency and cycles visible; it has no protocol- or project-specific assumptions. On a stopped DHO it briefly runs acquisition while applying horizontal scale, then returns to STOP. It also disables a retained delayed/zoom timebase so measurements and captures use the requested main view. Its result includes fully_applied, mismatches, and fields whose scope readback cannot verify directly. After stopping acquisition, capture_waveforms reads several channels from the same stopped acquisition, saves the raw arrays together and returns compact per-channel analysis.
Example arguments for configure_timing_capture:
{
"channels": [
{"channel": 1, "label": "CLOCK", "voltage_domain_v": 3.3},
{"channel": 2, "label": "DATA", "voltage_domain_v": 5.0}
],
"trigger": {"channel": 1, "slope": "POS"},
"signal_frequency_hz": 1000000,
"cycles_visible": 4,
"purpose": "Check clock-to-data timing"
}Labels and purpose are evidence metadata supplied by the caller, not interpreted as device semantics. Verify attenuation, probe loading and threshold assumptions against the actual circuit before relying on timing or voltage conclusions.
Agent Data Usage
Prefer numeric readings and local waveform analysis. Large results and raw arrays stay in files with compact metadata; images and inline binary are opt-in. Use read_capture for specific bounded excerpts, not entire files. Full data is retained. See transfer and output limits.
Safety
Use one server instance per physical scope and call instrument tools sequentially. Only trusted clients should have access: operations can change acquisition, overwrite scope files, reset the instrument, lock controls or change LAN settings.
Unrestricted send_raw is disabled by default. The documented DHO814 catalog is available without enabling it; catalog membership does not make an operation non-destructive. State-changing operations, error-queue reads and memory downloads are not automatically replayed after communication failures. A failed readback can follow a successful write; inspect current state before repeating a change.
Testing
The default suite is offline and needs no instrument. See container-based development checks to run tests or audit reference data without installing Python on the host. Image smoke tests also run in CI; see Docker tests. DHO814 LAN smoke tests passed on firmware 00.01.05 without an input signal. Additional Pico-driven acceptance tests cover statistics, cursors, search, mask, recording/replay, meters, math/reference, RAW transfers, setup restoration, and UART, I2C, and SPI decoding. CAN and parallel decoding, exhaustive behavior for all 897 catalog forms, destructive operations, and deliberate transport-fault recovery remain unverified. See the advanced acceptance report and hardware test coverage and instructions.
Acknowledgements
This independent project is based on erebusnz/rigol-mcp, originally created by Stig Manning. The original MIT license and copyright notice are preserved.
License
MIT — see LICENSE.
Available Tools
21 toolsautoscaleA
Run auto-setup, changing channels, timebase and trigger; wait for completion and return state. Not capability discovery or factory reset; no automatic retry.
Inputs: no named parameters.
check_errorA
Read/clear up to 16 SCPI error entries; return only the first, or 'No error'. No retries.
Inputs: no named parameters.
download_waveformA
Save a stopped DHO814 acquisition as time/value CSV; return path and timing. RAW/MAX read memory; NORM reads screen (required for math). Analog source must be enabled with data. Transfer settings are not restored; acquisition is unchanged.
Inputs: source (required), mode, start, points, +1 more.
get_capabilitiesA
Return model capabilities with per-field evidence: hardware-verified, documented or unverified. By default probe DHO800/900 channel/grid counts and report model mismatches; measurement lists are not accuracy validation. Probes read and clear SCPI errors. Set verify_hardware=false for identity/model data only.
Inputs: verify_hardware.
get_cursor_valuesA
Read cursor values and DHO source/type. AX_s/BX_s are seconds; XY axes are amplitudes. inv_delta_x is reciprocal separation, not necessarily signal frequency.
Inputs: no named parameters.
get_scope_stateB
Read channel settings, timebase and trigger mode/status; source/slope/level only for EDGE. Includes model capabilities without live channel/grid verification.
Inputs: no named parameters.
get_waveformA
Analyse NORM screen data (DHO 1000, DS1000Z up to 1200 points), suppressing unreliable interpretation. Does not stop acquisition; stop first for consistency. Enables disabled channels; acquisition may be needed. Leaves transfer settings changed. raw_data=true saves JSON and returns metadata/path, never samples. Use download_waveform for memory.
Inputs: channel (required), raw_data.
idnA
Read identity (model, serial, firmware) and LAN/session/driver diagnostics. Failure is reported in diagnostic text; inspect it, not only the MCP success flag.
Inputs: no named parameters.
measureA
Read a built-in measurement as text; get_capabilities lists items. Registers the item on the scope (may populate its results panel) and enables disabled channels. DHO may need live acquisition. 9.9E37 is invalid. VAMP uses pulse levels, VPP extrema; VRMS covers the window, PVRMS one period, ACRMS the AC component (DHO).
Inputs: item (required), channel (required).
measure_betweenA
Read delay (seconds) or phase (degrees). DHO edge letters refer to source1 then source2; DS1000Z R/F names map to DHO RR/FF. Registers a scope measurement (may populate results panel) and enables disabled sources. DHO may need live acquisition; 9.9E37 is invalid.
Inputs: item (required), source1 (required), source2 (required).
read_captureA
Read generated data files under RIGOL_DATA_DIR, not screenshots or arbitrary files. No scope access. Byte offsets; escaping may shorten excerpts: follow next_offset. UTF-8 boundaries may replace characters; base64 is lossless. Read only needed excerpts.
Inputs: path (required), offset, encoding, max_bytes.
runA
Start continuous acquisition; immediate status may lag. Query get_scope_state to confirm.
Inputs: no named parameters.
scpi_catalogA
Browse DHO814 command names (10 per page), or pass command for one signature, parameter types/enums and manual section. Filter by subsystem or search; command ignores other filters. No scope access. Fetch details before scpi_execute.
Inputs: limit, offset, search, command, +1 more.
scpi_executeA
Execute one DHO814 catalog command; arguments are positional. Text over 2048 characters and binary are file-backed; inline_binary permits up to 1024 bytes. Scope enforces dynamic limits. Non-reset writes drain errors; queries may consume status/errors. No retries or completion guarantee. Can overwrite files, reset, change LAN or lock controls. Does not require send_raw enablement.
Inputs: command (required), arguments, data_path, operation, +2 more.
screenshotA
Save a display PNG and return its path. Set include_image=true only when visual inspection is necessary; otherwise prefer measure/get_waveform.
Inputs: include_image.
set_channelA
Change specified channel settings; return channel readback. Probe ratio is applied before scale/offset; changing it may rescale existing values. Use an installed channel.
Inputs: channel (required), probe, display, coupling, +2 more.
set_cursorsA
Set cursors and return readouts; omitted mode is retained. DHO-only: source/type for MANUAL; source_a/source_b/track_axis for TRACK; Y positions. OFF accepts no positions or sources. XY is DHO-only, requires XY timebase, and rejects positions here; scpi_execute supports XY positioning on DHO814.
Inputs: ax, ay, bx, by, +6 more.
set_timebaseA
Set horizontal scale/offset; return configuration. Centered window edges are offset +/- 5scale on DHO800, +/- 6scale on DS1000Z. Use measured waveform bounds for zoom/noncentral references. Trigger level need not be zero volts.
Inputs: offset_s, scale_s_div.
set_triggerA
Always selects EDGE, even with no arguments; return readback. POS rises, NEG falls, RFAL accepts either edge. EXT is available on DHO802/DHO812, not DHO814.
Inputs: level, slope, source.
singleA
Arm one acquisition; return status without waiting for its trigger. Check get_scope_state for STOP before downloading.
Inputs: no named parameters.
stopA
Stop acquisition, retaining the displayed trace and settings. Immediate status may lag; confirm STOP via get_scope_state. Not a clear or factory reset.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools map to a distinct resource and action (configuration, acquisition, measurement, file output), but get_capabilities/idn/get_scope_state overlap on identity/model information, and get_waveform/download_waveform/read_capture all involve reading waveform-like data. Agents may occasionally need to read descriptions carefully to pick the right one.
The get_ and set_ verb-noun pattern is clear for state and configuration tools, but there are notable deviations: scpi_catalog, idn, screenshot, single, measure, run, stop, and autoscale use nouns, acronyms, or bare verbs. This mixed style is still readable, but not consistently predictable across the whole set.
At 21 tools, this exceeds the comfortable 3-15 range and feels heavy for an instrument-control server. The breadth is largely justified by the multiple subsystems (capabilities, waveform, measurement, cursors, SCPI, acquisition), but the count still borders on excessive.
The tool set covers configuration, the acquisition lifecycle (run/stop/single/autoscale), waveform retrieval and analysis, measurements, cursors, error handling, identity, and file output. The scpi_catalog/scpi_execute pair provides a low-level escape hatch for any missing SCPI operation, leaving no obvious dead ends.
Maintenance
Related MCP Connectors
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Toolstile is a managed MCP gateway that connects remote MCP servers behind one endpoint, with per-agent permissions, shared accounts and activity logs. Connect at https://mcp.toolstile.com/mcp over Streamable HTTP with OAuth; sign in at https://toolstile.com, select a workspace and connect your upstream servers. Available tools, resources and prompts depend on that workspace and the agent's granted access.
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Single-connection MCP gateway discovering and executing 490+ verified MCP & A2A tools.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI to control RIGOL DHO/HDO oscilloscopes and SIGLENT SDG1000X signal generators via SCPI commands through a local stdio MCP server.1-
- AlicenseAqualityDmaintenanceMCP server for controlling and reading Rigol DHO800/DHO900 oscilloscopes over LAN via SCPI commands.112MIT
- AlicenseNot gradedqualityCmaintenanceEnables MCP clients to connect to and control Siglent oscilloscopes and power supplies over SCPI/TCP using typed tool calls with input validation, safety controls, and built-in observability.1Apache 2.0
- AlicenseAqualityCmaintenanceEnables MCP-compatible AI clients to operate a RIGOL MHO98 oscilloscope over USB, including configuration, waveform and measurement acquisition, FFT analysis, and protocol decoding.16MIT