dso2d15-mcp

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