# Siglent Sds Mcp > A MCP server for Siglent SDX oscilloscopes - **Type:** MCP server - **Install:** `agentstack add mcp-magnusjohansson-siglent-sds-mcp` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [MagnusJohansson](https://agentstack.voostack.com/s/magnusjohansson) - **Installs:** 0 - **Category:** [Integrations](https://agentstack.voostack.com/c/integrations) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [MagnusJohansson](https://github.com/MagnusJohansson) - **Source:** https://github.com/MagnusJohansson/siglent-sds-mcp ## Install ```sh agentstack add mcp-magnusjohansson-siglent-sds-mcp ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # siglent-sds-mcp A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that lets AI assistants control Siglent oscilloscopes over your local network. Connect Claude to your bench and measure, capture, and configure your scope through natural language. ## Overview This MCP server communicates with Siglent SDS oscilloscopes via SCPI commands over TCP sockets (port 5025). No VISA drivers or NI-MAX installation required — just a network connection to your scope. *Oscilloscope display captured through the `screenshot` MCP tool.* *Natural-language scope control and measurement workflow in the terminal.* **Key features:** - 12 tools covering channels, timebase, triggers, measurements, waveform capture, and screenshots - Auto-connect on startup via environment variable - Query queue serializes commands automatically — tools can safely run in parallel - Waveform data returned as voltage/time arrays ready for analysis - Screenshots captured and converted to PNG for inline display in Claude - Raw SCPI escape hatch for any command not covered by the built-in tools ## Compatibility | Status | Model | |--------|-------| | Tested | SDS1104X-E | | Expected to work | SDS1000X-E series (SDS1202X-E, SDS1204X-E, etc.) | | May work | Other Siglent SDS models with SCPI over TCP support | The server uses standard SCPI commands from the [SDS1000X-E Programming Guide](https://siglentna.com/wp-content/uploads/dlm_uploads/2017/10/ProgrammingGuide_forSDS-1702.pdf). Other Siglent models that support the same command set over port 5025 should work with little or no modification. ## Quick Start You need a Siglent oscilloscope accessible on your network (TCP port 5025). Pick one of the three options below and add the config to your `.mcp.json` (in your project directory, or `~/.claude/.mcp.json` for global access). Replace `192.168.1.126` with your scope's IP address. ### Option A: Docker (recommended) No Node.js installation required. Works on Linux, macOS, and Windows (via WSL2 or Docker Desktop). ```json { "mcpServers": { "siglent-sds": { "type": "stdio", "command": "docker", "args": [ "run", "--rm", "-i", "-e", "SIGLENT_IP=192.168.1.126", "ghcr.io/magnusjohansson/siglent-sds-mcp:latest" ] } } } ``` ### Option B: npx Requires Node.js 20+. Downloads and runs the package automatically. ```json { "mcpServers": { "siglent-sds": { "type": "stdio", "command": "npx", "args": ["-y", "siglent-sds-mcp"], "env": { "SIGLENT_IP": "192.168.1.126" } } } } ``` ### Option C: Clone and build ```bash git clone https://github.com/magnusjohansson/siglent-sds-mcp.git cd siglent-sds-mcp npm install npm run build ``` ```json { "mcpServers": { "siglent-sds": { "type": "stdio", "command": "node", "args": ["/path/to/siglent-sds-mcp/build/index.js"], "env": { "SIGLENT_IP": "192.168.1.126" } } } } ``` Replace `/path/to/siglent-sds-mcp` with the actual path to your clone. ### Environment Variables | Variable | Required | Default | Description | |----------|----------|---------|-------------| | `SIGLENT_IP` | No | — | Oscilloscope IP address for auto-connect on startup | | `SIGLENT_PORT` | No | `5025` | TCP port (only change if your setup differs) | ### Auto-Connect Behavior If `SIGLENT_IP` is set, the server attempts to connect to the scope immediately after starting. This runs in the background and does **not** block the MCP server — Claude can start using other tools right away. If the scope is offline or unreachable, the server logs a warning and you can connect manually later using the `connect` tool. If `SIGLENT_IP` is not set, the server starts without a scope connection. Use the `connect` tool to connect when ready. ## Using with Other AI Clients The Quick Start examples above use Claude Code's `.mcp.json` format, which includes a `"type": "stdio"` field. Other AI clients use the same JSON structure but **without** the `"type"` field and with different config file locations. ### Claude Desktop Edit `claude_desktop_config.json`: - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` #### Docker ```json { "mcpServers": { "siglent-sds": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "SIGLENT_IP=192.168.1.126", "ghcr.io/magnusjohansson/siglent-sds-mcp:latest" ] } } } ``` #### npx ```json { "mcpServers": { "siglent-sds": { "command": "npx", "args": ["-y", "siglent-sds-mcp"], "env": { "SIGLENT_IP": "192.168.1.126" } } } } ``` > **Note:** You must fully restart Claude Desktop after changing the config file. ### Cursor Edit one of: - **User-level:** `~/.cursor/mcp.json` (available across all projects) - **Project-level:** `.cursor/mcp.json` (shared with your team via version control) You can also add servers through the UI: **Settings > Cursor Settings > MCP > Add new global MCP server**. #### Docker ```json { "mcpServers": { "siglent-sds": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "SIGLENT_IP=192.168.1.126", "ghcr.io/magnusjohansson/siglent-sds-mcp:latest" ] } } } ``` #### npx ```json { "mcpServers": { "siglent-sds": { "command": "npx", "args": ["-y", "siglent-sds-mcp"], "env": { "SIGLENT_IP": "192.168.1.126" } } } } ``` ### Windsurf Edit `mcp_config.json`: - **Windows:** `%USERPROFILE%\.codeium\windsurf\mcp_config.json` - **macOS/Linux:** `~/.codeium/windsurf/mcp_config.json` You can also configure servers through the UI: **Cascade panel > MCP icon > Manage MCP Servers > View raw config**. #### Docker ```json { "mcpServers": { "siglent-sds": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "SIGLENT_IP=192.168.1.126", "ghcr.io/magnusjohansson/siglent-sds-mcp:latest" ] } } } ``` #### npx ```json { "mcpServers": { "siglent-sds": { "command": "npx", "args": ["-y", "siglent-sds-mcp"], "env": { "SIGLENT_IP": "192.168.1.126" } } } } ``` ### Google Antigravity Configuration is managed through the IDE's UI: 1. Open the **Agent pane** on the right side of the workspace 2. Click the **`...`** button at the top 3. Select **MCP Servers** 4. Click **Manage MCP Servers** 5. Click **View raw config** 6. Add the configuration below and save #### Docker ```json { "mcpServers": { "siglent-sds": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "SIGLENT_IP=192.168.1.126", "ghcr.io/magnusjohansson/siglent-sds-mcp:latest" ] } } } ``` #### npx ```json { "mcpServers": { "siglent-sds": { "command": "npx", "args": ["-y", "siglent-sds-mcp"], "env": { "SIGLENT_IP": "192.168.1.126" } } } } ``` Replace `192.168.1.126` with your scope's IP address in all examples above. ### ChatGPT Desktop ChatGPT Desktop only supports remote HTTPS MCP servers (called "connectors"), not local stdio servers. Since this MCP server uses stdio transport, it is not directly compatible with ChatGPT Desktop. ## Tools 12 tools across 6 categories. See [docs/tools-reference.md](docs/tools-reference.md) for full parameter details. | Category | Tool | Description | |----------|------|-------------| | Connection | `connect` | Connect to oscilloscope over TCP | | | `disconnect` | Close the connection | | | `identify` | Query device ID (manufacturer, model, serial, firmware) | | Channel | `get_channel` | Read channel configuration (vdiv, offset, coupling, etc.) | | | `configure_channel` | Set vdiv, offset, coupling, bandwidth limit, trace, probe | | Acquisition | `get_acquisition_status` | Read timebase, sample rate, trigger settings | | | `configure_acquisition` | Set timebase, trigger, run/stop/single | | Measurement | `measure` | Read a measurement (frequency, Vpp, RMS, etc.) | | | `measure_statistics` | Enable/read/reset measurement statistics | | Waveform | `get_waveform` | Download voltage/time data arrays | | | `screenshot` | Capture scope screen as PNG | | SCPI | `scpi_query` / `scpi_command` | Send arbitrary SCPI commands | ## Example Conversations ### Read a channel configuration > **You:** What's the current setup on channel 1? > > Claude calls `get_channel` with `channel: "C1"` and returns the volts/div, offset, coupling, and other settings. ### Measure a signal > **You:** Measure the frequency and peak-to-peak voltage on channel 2. > > Claude calls `measure` twice — once with `parameter: "FREQ"` and once with `parameter: "PKPK"` on channel C2 — and reports both values. ### Capture and analyze a waveform > **You:** Download the waveform from channel 1 and tell me what you see. > > Claude calls `get_waveform` on C1, receives voltage/time data, and analyzes the signal shape, frequency, amplitude, and any anomalies. ### Take a screenshot > **You:** Show me what the scope screen looks like right now. > > Claude calls `screenshot`, receives a base64 BMP image, and displays it inline. ### Configure the scope for a specific measurement > **You:** Set up channel 1 for a 3.3V logic signal — DC coupling, 1V/div, trigger on the rising edge at 1.6V. > > Claude calls `configure_channel` (setting vdiv, coupling) and `configure_acquisition` (setting trigger source, level, slope) in sequence. ## Architecture ``` Claude Code siglent-sds-mcp Oscilloscope:5025 ``` - **Transport:** MCP over stdio (JSON-RPC 2.0) - **Protocol:** SCPI commands over raw TCP sockets, newline-terminated - **Query Queue:** All SCPI queries are serialized through an internal queue. The oscilloscope processes one command at a time, so even when tools issue parallel requests (via `Promise.all`), the queue ensures they're sent sequentially. - **Binary Block Parsing:** Waveform and screenshot data use IEEE 488.2 definite-length block format (`#9XXXXXXXXX` + data bytes + `\n\n`). The connection layer detects and parses these automatically. - **Voltage Reconstruction:** Raw ADC codes are converted to voltages: `code * (vdiv / 25) - offset`, with two's complement handling for signed values. ## Development ```bash npm run build # Compile TypeScript npm run watch # Watch mode — recompile on changes npm run dev # Build and run npm run inspector # Launch with MCP Inspector for debugging ``` ### Docker (local build) Build the image locally: ```bash docker build -t siglent-sds-mcp . ``` Then use the local image in your `.mcp.json`: ```json { "mcpServers": { "siglent-sds": { "type": "stdio", "command": "docker", "args": [ "run", "--rm", "-i", "-e", "SIGLENT_IP=192.168.1.126", "siglent-sds-mcp" ] } } } ``` ### Project Structure ``` src/ index.ts # Entry point, MCP server setup connection.ts # TCP socket manager with query queue tools/ connection.ts # connect, disconnect, identify channel.ts # get_channel, configure_channel acquisition.ts # configure_acquisition, get_acquisition_status measure.ts # measure, measure_statistics waveform.ts # get_waveform, screenshot scpi.ts # scpi_query, scpi_command ``` ## Troubleshooting ### "Not connected to oscilloscope" The scope isn't connected yet. Either set `SIGLENT_IP` in your `.mcp.json` env for auto-connect, or use the `connect` tool manually. ### Connection timeout - Verify the scope's IP address (check the scope's Utility > Interface menu) - Ensure port 5025 is accessible (try `telnet 5025` from your machine) - Check that no firewall is blocking the connection - The scope only accepts one TCP connection at a time — close any other SCPI clients ### Query timeout Some SCPI queries can take a few seconds, especially on slower scope models. The default timeout is 5 seconds. For `scpi_query`, you can increase the timeout with the `timeout_ms` parameter. ### Docker: can't reach the oscilloscope By default, Docker containers can reach LAN devices via the bridge network (NAT). If the container can't connect to your scope: - Verify the scope is reachable from your host: `telnet 192.168.1.126 5025` - On Linux, try adding `--network host` to the Docker args: ```json "args": ["run", "--rm", "-i", "--network", "host", "-e", "SIGLENT_IP=192.168.1.126", "ghcr.io/magnusjohansson/siglent-sds-mcp:latest"] ``` Note: `--network host` does not work on macOS or Windows Docker Desktop. ### Docker: wrong architecture / exec format error The published image supports `linux/amd64` and `linux/arm64`. Docker should pull the correct one automatically. If you see an exec format error, pull explicitly: ```bash docker pull --platform linux/amd64 ghcr.io/magnusjohansson/siglent-sds-mcp:latest ``` ### "CHDR" appears in responses This shouldn't happen — the server sets `CHDR OFF` on connect. If you see command headers in responses, try disconnecting and reconnecting. ## License MIT — see [LICENSE](LICENSE) for details. ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [MagnusJohansson](https://github.com/MagnusJohansson) - **Source:** [MagnusJohansson/siglent-sds-mcp](https://github.com/MagnusJohansson/siglent-sds-mcp) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-magnusjohansson-siglent-sds-mcp - Seller: https://agentstack.voostack.com/s/magnusjohansson - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.