Siglent SCPI MCP Server

siglent-scpi-mcp connects Siglent oscilloscopes and power supplies using SCPI over TCP to clients that support the Model Context Protocol.

The server provides typed tools for supported instruments, validates tool inputs before writing to the instrument, and reports the SCPI commands applied by each mutating call. Structured logs and OpenTelemetry observability are built in.

Supported instruments

The table describes the built-in model routing. It does not mean that each model has been tested on hardware.

An unsupported instrument still gets the identify and status tools. Raw SCPI tools can also be enabled, but their command support is unknown and they are not exposed by default.

You can extend model recognition with an inventory file.

Related MCP server: keyscope-mcp

Requirements

• Node.js 24 or newer

• Network access from the server to the instrument

• SCPI over TCP enabled on the instrument, normally on port 5025

• An MCP client that supports Streamable HTTP

Quick start

Docker image

Run the prebuilt image published by the latest successful main build:

export SIGLENT_MCP_TOKEN="$(openssl rand -hex 32)"
echo "Token: $SIGLENT_MCP_TOKEN"
docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -e SIGLENT_MCP_TOKEN \
  ghcr.io/mp911de/siglent-scpi-mcp:main \
  --listen 0.0.0.0 \
  192.168.1.50

The container requires a bearer token because it listens on a non-loopback address internally.

npm

Install the command globally from npm:

npm install --global @mp911de/siglent-scpi-mcp
siglent-scpi-mcp 192.168.1.50

To install the latest GitHub revision instead, use the repository shorthand:

npm install --global mp911de/siglent-scpi-mcp
siglent-scpi-mcp 192.168.1.50

Replace 192.168.1.50 with the instrument host or IP address. Add :<port> when the instrument does not use port 5025.

Startup connects to the instrument and reads *IDN? before it opens the MCP endpoint at:

http://127.0.0.1:3000/mcp

In another terminal, confirm that the server is running and the instrument connection is open:

curl http://127.0.0.1:3000/healthz

{"status":"ok","instrument":{"connected":true}}

Register the endpoint with an MCP client. For example, register the Docker container with its bearer token in Claude Code:

claude mcp add --transport http siglent http://127.0.0.1:3000/mcp \
  --header "Authorization: Bearer $SIGLENT_MCP_TOKEN"

For the default npm command, which binds directly to host loopback without a token, use:

claude mcp add --transport http siglent http://127.0.0.1:3000/mcp

The server must remain running while the client uses the instrument.

Configuration

Command line

Usage: siglent-scpi-mcp [options...] <host>[:port]

Exit status:

• 0 after a clean shutdown

• 1 when startup cannot reach or identify the instrument

• 2 for a usage error

Terminal colors are used only when stdout and stderr are terminals and NO_COLOR is not set.

Tool discovery

The selected driver determines which tools are available. Typical oscilloscope tool groups include acquisition, channels, trigger, waveform search, serial decode, mask testing, waveform, math and FFT, measurements, cursors, saved setups and stored files, system settings, screenshots, and device-specific features. The newer dialect also exposes waveform generator and handheld multimeter tools. Neither is hidden per model, because nothing in the instrument identity reports the generator option.

Security model

• The server binds to loopback by default.

• Loopback requests validate Host and Origin to reduce DNS rebinding risk.

• A non-loopback bind requires bearer authentication.

• Prefer SIGLENT_MCP_TOKEN to --token, since command lines may be visible to other users.

The health endpoint does not require authentication. It reports only server status and whether the instrument connection is open.

Safe tool exposure

The server hides destructive/dangerous tools by default:

• reboot_scope

• shutdown_scope

• calibrate_scope

• configure_lan

• scpi_command

• scpi_query

• save_waveform_file

• clear_measurements

• capture_screenshot

• lock_front_panel

Enable reboot, shutdown, calibration, LAN, and raw SCPI tools with:

siglent-scpi-mcp --enable-dangerous-commands 192.168.1.50

Enable screenshots separately:

siglent-scpi-mcp --enable-screenshots 192.168.1.50

Add --save-screenshots to also write every capture to disk in a session directory like 2026-09-01T1421_SDS1204X-HD/.

This can be useful to prevent LLMs from taking shortcuts.

You can narrow the exposed surface further:

siglent-scpi-mcp \
  --enable-dangerous-commands \
  --disable-commands scpi_command \
  --disable-destructive-commands \
  192.168.1.50

--disable-commands takes a comma-separated list of tool names. --disable-setup-commands hides setup mutations. --disable-destructive-commands hides destructive tools. Disable options always take precedence over enable options.

Front panel lock

A remote lock makes an instrument read as stuck to a person standing at it, so locking is opt-in and unlocking is always allowed.

• --unlock clears the lock when the server connects.

• --enable-lock enables locking (disabled by default).

The SDS1204X HD engages its remote lock on its own during waveform transfers, undocumented firmware behaviour observed on the bench.

Custom model inventory

--inventory <file> overlays additional model matches onto the built-in family table. A key that names a built-in family can add models without repeating the family declaration. A new key must define at least its device kind.

{
  "SDS X HD": {
    "models": ["SDS1204X HD", {"pattern": "^SDS8\\d{2}X HD"}]
  },
  "Lab supply": {
    "kind": "power-supply",
    "psu": "SPD1000X",
    "models": ["SPD1168X-CUSTOM"]
  }
}

Exact model strings take precedence over regular expression patterns. Inventory entries take precedence over the built-in table.

Observability

Traces

One tool call is one trace. Its root span is named tool <name> and carries the tool name in the mcp.tool.name attribute. Every SCPI exchange the call makes becomes a child span named scpi.query, scpi.command, or scpi.binary, carrying the line sent in the scpi.command attribute. A get_timebase call, for instance, is one root span over four scpi.query children. The connection handshake runs before any tool call, so *IDN? and CHDR OFF show up as short traces of their own at startup.

The server depends on the OpenTelemetry API alone, so every span is a no-op until a tracing SDK is registered in the process. Nothing leaves the server until you attach one.

Traces in Grafana

examples/observability holds a backend and the preload module that turns the spans on. The backend is grafana/otel-lgtm, Grafana's own single-container OpenTelemetry stack for demos and development. It publishes Grafana on port 3000, Tempo on 3200, and the OTLP HTTP endpoint on 4318.

The preload needs @opentelemetry/sdk-node, which is a development dependency of this project.

Start the backend:

docker compose -f examples/observability/compose.yaml up -d

Start the server with the preload:

OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318 \
  node --import ./examples/observability/otel.ts src/cli.ts --port 3001 192.168.1.50

Docker

Build the image:

docker build -t siglent-scpi-mcp .

Run it with the HTTP port published only on host loopback:

docker run --rm \
  -p 127.0.0.1:3000:3000 \
  -e SIGLENT_MCP_TOKEN=change-me \
  siglent-scpi-mcp \
  --listen 0.0.0.0 \
  192.168.1.50

The process must bind to 0.0.0.0 inside the container for Docker port publishing to reach it. A non-loopback bind requires a bearer token. Configure the same token in the MCP client. The container must also be able to reach the instrument on TCP port 5025.

Documentation

• Tool reference

• Tool parity between the two oscilloscope dialects

License

Siglent SCPI MCP Server is released under version 2.0 of the Apache License.