Generic SCPI Instrument

Generic SCPI Instrument — MCP Server

Let an AI agent talk to any IEEE 488.2 / SCPI instrument: multimeters, oscilloscopes, source-measure units, power supplies, electronic loads, function generators, spectrum analyzers and counters. It works over GPIB, USBTMC, LAN (VXI-11, HiSLIP, raw socket) and RS-232. Because the agent writes raw SCPI, the server puts the safety in the plumbing. The read path accepts only single queries. Anything that changes the instrument goes through tools the MCP client asks you to confirm. You can give the server command allow and deny lists and a safe-state command of your own.

Keysight or Rohde & Schwarz instrument? Use the vendor's official MCP server instead: Keysight MCP Server for Instrument Control or the MCP server that ships with RsInstrument (python -m RsInstrument.mcp). labmcp-scpi covers everything else: Tektronix/Keithley, Rigol, Siglent, SRS, Aim-TTi, B&K Precision, GW Instek, older HP/Agilent GPIB gear, and more.

Try it without hardware

uvx labmcp-scpi --simulate --check

The simulator is a small, generic bench instrument (*IDN? → LabMCP,SIM-DMM-PSU,SIM000001,1.0.0). It is a 0–30 V / 3 A supply driving a 100 Ω load, with a built-in DMM across the load. It supports MEASure:VOLTage:DC?, CONFigure + READ?/FETCh?, [SOURce:]VOLTage/CURRent, OUTPut[:STATe], TRIGger:COUNt, FORMat[:DATA] REAL,32|64 binary blocks, FORMat:BORDer, *ESR?/*STB?, and a 10-entry SYSTem:ERRor? queue (overflow gives -350). In --simulate mode, the safe state is OUTP OFF.

Connect your instrument

1. Instrument setup: enable the remote interface you want to use.
   • LAN: set a fixed IP address. Enable VXI-11/HiSLIP (for VISA) or the SCPI raw-socket server. Many instruments use port 5025 for the socket; check the LAN settings page or the manual.
   • USB: select USBTMC / "USB device (TMC)", not "USB mass storage" or a virtual COM port.
   • GPIB: note the instrument's GPIB address.
   • RS-232: set the baud rate, parity and handshake, and select SCPI as the language if the instrument asks.
2. Find it: uvx labmcp ports, or ask the agent to run list_visa_resources. That tool works without --address and lists VISA resources through pyvisa-py; pass backend=@ivi to use NI-VISA or another vendor VISA library.
3. Test the connection:
   bash

   uvx labmcp-scpi --address visa://TCPIP0::192.168.1.50::inst0::INSTR --check      # LAN, VXI-11uvx labmcp-scpi --address visa://TCPIP0::192.168.1.50::hislip0::INSTR --check    # LAN, HiSLIPuvx labmcp-scpi --address tcp://192.168.1.50:5025 --check                        # raw socketuvx labmcp-scpi --address "visa://USB0::0x1AB1::0x0588::DS1ZA000000::INSTR" --checkuvx labmcp-scpi --address "visa://GPIB0::22::INSTR?backend=@ivi" --check         # NI-VISAuvx labmcp-scpi --address "serial:///dev/ttyUSB0?baudrate=9600&read_termination=CRLF" --check

   --check prints the parsed *IDN? reply. If it times out, check the terminator: SCPI uses LF by default, and some serial instruments need read_termination=CRLF. Also check the baud rate, and that the instrument is set to SCPI rather than an emulation language.

Add to your MCP client

Claude Code

claude mcp add scope -- uvx labmcp-scpi --address visa://TCPIP0::192.168.1.50::inst0::INSTR

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, .cursor/mcp.json, …)

{  "mcpServers": {    "psu": {      "command": "uvx",      "args": [        "labmcp-scpi", "--address", "tcp://192.168.1.50:5025",        "--option", "safe_state=OUTP OFF",        "--option", "write_denylist=^OUTP\\d*(:STAT)? (?!OFF\\b)"      ]    }  }}

Add --read-only to allow only queries. In read-only mode scpi_write, scpi_batch and reset_instrument disappear. device_clear and apply_safe_state stay available. Run one server per instrument, each with its own key (scope, psu, dmm, …).

Tools

get_connection_info, get_command_log and reconnect are built into every LabMCP server. apply_safe_state is listed only when a safe state is configured.

Command policy

A generic server cannot know which SCPI commands are dangerous on your instrument. It enforces what it can and lets you add the rest:

Matching rules:

• Patterns are Python regular expressions, matched case-insensitively.
• Each ;-separated message unit is checked in two forms. The first is the unit as sent, upper-cased, with collapsed whitespace and no leading colon. The second reduces every mnemonic to its SCPI short form (SCPI-99 Vol. 1 §6.2.1): :OUTPut1:STATe ON becomes OUTP1:STAT ON. So ^OUTP\d*(:STAT)? (?!OFF\b) catches OUTP ON, outp:stat 1, VOLT 5;:OUTPut:STATe ON and OUTPut2 ON.
• SCPI booleans accept any number (it is rounded, and anything non-zero means ON), so OUTP 2, OUTP 1.0 and OUTP #H1 also switch an output on. Deny "everything except OFF", as above, rather than listing (ON|1).
• The denylist uses re.search. It also resolves relative headers (OUTP:POL NORM;STAT ON is checked as OUTP:STAT ON) and splits at every ;, even inside quotes. The allowlist must match a whole unit.
• Every step of scpi_batch is checked before the first step is sent.

Examples:

# Power supply: the agent may set levels and switch the output OFF, but only a human switches it on--option 'write_denylist=^OUTP\d*(:STAT)? (?!OFF\b)' --option 'safe_state=OUTP OFF'# DMM: allow measurement configuration only--option 'write_allowlist=(CONF|SENS|TRIG|INIT|FORM|ABOR)(:\S+)*( .*)?'# SMU: measuring can switch the output on, so require confirmation for it--option 'query_denylist=^(MEAS|READ)' --option 'safe_state=OUTP OFF'

The environment variable LABMCP_OPTIONS splits on commas. For regular expressions that contain commas, pass them on the command line or give LABMCP_OPTIONS as a JSON object ({"write_denylist": "..."}).

Safety limits

Override at launch: --limit max_block_bytes=67108864. This server has no voltage or current limits because it cannot interpret arbitrary commands. Set limits on the instrument itself (OVP/OCP, compliance, output protection), use a denylist, or use an instrument-specific server.

Example prompts

• "What instrument is connected? Read its identity and check the error queue."
• "Configure the DMM for DC volts on the 10 V range, take 20 readings, and give me the mean and standard deviation."
• "Set the supply to 3.3 V with a 200 mA current limit, read both back, but don't enable the output yet."
• "Grab channel 1's waveform from the scope as a binary block, save it to ~/data/ch1.csv, and summarise min, max and mean."
• "We got a -222 error. What does it mean, and which of the last commands caused it?"
• "Something's wrong: apply the safe state, then clear the interface."

Notes

• A generic server cannot make an arbitrary instrument safe. device_clear does four things: a VISA device clear (on raw socket and serial links it only discards unread input), reads the error queue, sends ABORt, and sends *CLS. It recovers communication and stops sweeps. It does not switch outputs off. Configure safe_state for anything that sources energy. For hazardous gear, use an instrument-specific LabMCP server where one exists: it can enforce real setpoint limits.
• Queries are not always read-only. On source-measure units such as the Keithley 2400, MEASure?, READ?, INITiate and CONFigure can switch the source output on (Keithley 2400 Series SourceMeter User's Manual, 2400S-900-01 Rev. G, §11 and §17). In --read-only mode, scpi_query therefore refuses MEASure? and READ? by default, while FETCh? still returns the last reading. Set --option allow_measure_in_read_only=true if the instrument is a meter that cannot source. When not read-only, add --option query_denylist=^(MEAS|READ) for SMUs so these commands need confirmation through scpi_write.
• *RST: SCPI-99 Vol. 2 §15.12 requires OUTPut:STATe OFF after *RST. But *RST also resets levels, ranges, limits and trigger settings, and not every instrument complies.
• The error queue is read (and so cleared) after every scpi_write/scpi_batch step. The errors appear in the result. A query the instrument doesn't recognise produces no reply: the server times out (5 s by default, --timeout to change), resynchronises, and reports the -113 from the queue.
• Instruments that don't implement SYSTem:ERRor? (some older IEEE 488.2-only gear) report error_check: "unavailable". Set --option error_query=… if your instrument uses a different error query.
• query_binary_block reads definite-length blocks (#<n><len><data>) only. Indefinite #0 blocks are refused. Byte order follows FORMat:BORDer (NORMal = big-endian). timeout_s covers the whole transfer. Decoded NaN and infinite values are returned as null (and counted in non_finite); the saved CSV keeps them as nan/inf.
• save_path must end in .csv (decoded values with decode_as, otherwise the raw bytes), .bin, .dat, .raw, .txt or an image extension (.png, .bmp, .jpg, .jpeg, .gif, .tif, .tiff). ~ is expanded and missing folders are created. An existing file is never replaced unless you pass overwrite=true, and the check happens before anything is sent to the instrument.
• scpi_batch stops starting new steps after about 14 minutes (its tool timeout is 15 minutes). Steps that were not sent are marked not_run.
• Text is sent as ASCII. Commands with control or non-ASCII characters are refused, and the server adds the LF terminator.
• A denylist is a guard rail, not a guarantee. It matches text, so vendor-specific aliases or macros (*DMC, user-defined sequences) can evade it. Keep the instrument's own protection limits set.

Hardware verification