dso2d15-mcp

A Model Context Protocol (MCP) server for the Hantek DSO2D15 (and other DSO2000-family scopes) using USB and SCPI over PyVISA (pyvisa-py backend by default).

Official SCPI reference: DSO2000 Series SCPI Programmer’s Manual (PDF).

Waveform acquisition follows the same PRIVate:WAVeform:DATA:ALL? flow used in community tooling (hantek-dso2000).

Requirements

• Python 3.10+
• USB connection to the scope (rear USB device port)
• OS support for USB-TMC via PyVISA:
  • Linux: often works with usbcore / usbtmc kernel driver or libusb stack used by pyvisa-py
  • macOS: install includes pyusb so pyvisa-py can enumerate USB-TMC. If discovery still fails, try NI-VISA and DSO2D15_VISA_BACKEND=@ni.

DSO2D15 USB IDs (matches VISA USB0::1183::20574::…): Vendor 0x049F (1183), Product 0x505E (20574). Example serial: CN5546029098237 → resource like USB0::1183::20574::CN5546029098237::0::INSTR.

If opening the instrument fails with usb.core.USBError: … Access denied (insufficient permissions) on macOS, pyvisa-py cannot claim the USB-TMC interface via libusb. Install NI-VISA, set DSO2D15_VISA_BACKEND=@ni, and use the NI resource string, or fix libusb access for that device (vendor docs / system USB policy).

Install

cd dso2d15-mcp
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

Run the server (stdio transport for Cursor/Claude Desktop):

dso2d15-mcp
# or
python -m dso2d15_mcp.server

Environment variables

Variable	Purpose
DSO2D15_VISA	Full VISA resource string, e.g. USB0::0x049F::0x505E::...::INSTR (use dso2d15_list_visa_resources to discover)
DSO2D15_VISA_QUERY	Pattern for auto-pick when DSO2D15_VISA is unset. Default: USB0::1183::20574:?* (Hantek DSO2000 IDs used by common tooling)
DSO2D15_TIMEOUT_MS	VISA read timeout in ms (default 120000; large captures can be slow)
DSO2D15_VISA_BACKEND	PyVISA resource manager string (default @py for pyvisa-py)
DSO2D15_SNAPSHOT_DIR	Directory for BMP/SVG files from dso2d15_measure_snapshot (default: system temp)

Cursor MCP configuration

Add to your MCP settings (adjust the path):

{
  "mcpServers": {
    "dso2d15": {
      "command": "/absolute/path/to/dso2d15-mcp/.venv/bin/dso2d15-mcp",
      "env": {
        "DSO2D15_VISA": "USB0::...your resource...::INSTR"
      }
    }
  }
}

Tools

Tool	Description
dso2d15_list_visa_resources	List VISA resources (query parameter, default ?*)
dso2d15_list_hantek_candidates	List resources matching DSO2D15_VISA_QUERY
dso2d15_identify	*IDN?
dso2d15_scpi_write	Send a SCPI command with no query response
dso2d15_scpi_query	ASCII query (responses that are not binary blocks)
dso2d15_scpi_query_binary	Binary/block responses (returns length + base64 preview)
dso2d15_fetch_waveform	High-level waveform JSON via PRIVate:WAVeform:DATA:ALL?
dso2d15_measure_vpp_frequency	Automatic Vpp and frequency via :MEASure:CHANnel<n>:ITEM?
dso2d15_measure_snapshot	Vpp + freq, optional BMP screen grab (best-effort), and SVG waveform plot path

Use dso2d15_scpi_query for interactive exploration (examples: *IDN?, :CHANnel1:SCALe?, :TIMebase:MAIN:SCALe?). Refer to the Hantek PDF for the full command set.

License

MIT