oscilloscope-mcp

AI-driven USB oscilloscope control via FastMCP 3.2. Connect screenless PC scopes (PicoScope, Hantek) or run the built-in simulator for dry-runs. Capture waveforms, export CSV, and compute frequency, Vpp, duty cycle, and rise time from your agent.

How it runs

Mode	Hardware	When
Simulator (default)	None	Development, CI, agent dry-runs
PicoScope	PicoScope 2000/3000/5000/6000 USB	Production bench with PicoSDK + pyPicoSDK
Hantek	Hantek 6022BE/BL	Budget USB scope with PyHT6022 + libusb

The MCP server never bundles oscilloscope drivers or PicoSDK. Install vendor software separately, then point the backend at your device.

Hands-in / Hands-out

Direction	Artifacts	Notes
Hands-in	device_id, channel config, trigger settings	Via scope_device, scope_configure, scope_trigger
Hands-out	Waveform preview (downsampled JSON)	scope_capture(operation="single")
Hands-out	CSV + JSON summary files	scope_capture(operation="export_csv") in OSCILLOSCOPE_MCP_CAPTURE_DIR
Hands-out	Measurements (Vpp, freq, duty, rise)	scope_measure(operation="all")

Fleet pipelines

Partner MCP	Workflow
kicad-mcp	Probe clock/reset nets after bring-up
chip-design-mcp	Verify power rails and oscillators
devices-mcp	Discover USB devices before connect

Quick Start

Set-Location D:\Dev\repos\oscilloscope-mcp
uv sync --extra dev
just webapp
# Open http://localhost:10937

STDIO-only (Cursor MCP):

just serve

Dry-run without hardware:

scope_device(operation="connect", device_id="sim-001")
scope_capture(operation="single", sample_rate_hz=100000, sample_count=2000)
scope_measure(operation="all", channel_id="A")

Cursor MCP config

Add to C:\Users\sandr\.cursor\mcp.json:

"oscilloscope-mcp": {
  "command": "C:/Users/sandr/.local/bin/uv.exe",
  "args": [
    "--directory",
    "D:/Dev/repos/oscilloscope-mcp",
    "run",
    "python",
    "-m",
    "oscilloscope_mcp",
    "--stdio"
  ],
  "env": {
    "FASTMCP_BANNER": "0",
    "FASTMCP_UPDATE_CHECK": "0",
    "PYTHONUNBUFFERED": "1",
    "OSCILLOSCOPE_MCP_BACKEND": "auto"
  }
}

Table of Contents

• Hardware Guide
• Backend Drivers
• Setup & Configuration
• Tool Catalog
• Architecture
• Safety
• Fleet Integration
• Install (naked PC)

Tools Overview

Tool	Operations	Purpose
scope_device	list, connect, disconnect, status, capabilities, backends	Device discovery and session
scope_configure	channel, get, simulator_profile	Voltage range, coupling, sim waveform
scope_trigger	set, get, arm, force	Trigger source, threshold, edge
scope_capture	single, preview, export_csv, export_summary, last	Acquire and export waveforms
scope_measure	all, vpp, frequency, duty, rise_time, fresh	Timing and voltage metrics
scope_help	discover, tool_help, quickstart, faq, hardware_guide	Discovery and buying guide

Recommended Hardware

Tier	Model	Price	Backend
Best value	PicoScope 2204A	~$130-190	picoscope
Swiss army knife	Analog Discovery 3	~$200-400	planned (waveforms)
Budget hack	Hantek 6022BE	~$40-80	hantek

See docs/HARDWARE.md for the full buying guide.

Webapp

Fleet SOTA console: Dashboard, Waveform viewer, Tools hub, Settings, Help.

just webapp

Port	Service
10936	FastAPI backend (/api/*, /health, /mcp)
10937	Vite React frontend

License

MIT - see LICENSE.