PicoScope MCP Server

A STDIO MCP server that enables LLMs like Claude to interact with PicoScope oscilloscopes for signal acquisition, measurement, and analysis. Built with FastMCP and the official PicoSDK Python bindings.

Features

• Device Management: Auto-discover and connect to PicoScope devices
• Channel Configuration: Set voltage ranges, coupling, and offsets
• Data Acquisition: Block capture and streaming modes
• Triggering: Simple and advanced trigger configurations
• Measurements: Frequency, amplitude, rise time, FFT, THD, and more
• Signal Generation: Control built-in arbitrary waveform generator
• AI-Native: Designed for natural language control via Claude and other LLMs

Quick Start

# Clone the repository
git clone https://github.com/markuskreitzer/picoscope_mcp.git
cd picoscope_mcp

# Install dependencies (requires uv package manager)
uv sync

# Run the MCP server
uv run picoscope-mcp

The server runs in STDIO mode and is ready to communicate with MCP clients like Claude Desktop.

Installation

Prerequisites

1. PicoSDK C Libraries (required for hardware operation)

   • Windows: Download from PicoTech Downloads
   • macOS: Download PicoScope software package
   • Linux: Install via package manager:

     # Ubuntu/Debian
     sudo apt-get install libps5000a libps4000a libps3000a libps2000a
     

2. Python 3.11+ with uv package manager

Install Dependencies

# Clone or navigate to the project directory
cd picoscope_mcp

# Install dependencies
uv sync

Usage

Running the Server

uv run picoscope-mcp

The server runs in STDIO mode, communicating via standard input/output for use with MCP-compatible clients.

Using with Claude Desktop

Add this configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "picoscope": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/picoscope_mcp",
        "run",
        "picoscope-mcp"
      ]
    }
  }
}

Restart Claude Desktop, and you'll see the PicoScope tools available in the MCP menu.

Testing Without Hardware

The server will run even without PicoScope hardware connected, though device operations will fail until:

1. PicoSDK C libraries are installed
2. A PicoScope device is connected

MCP Tools

Discovery & Connection

Tool	Description
list_devices	Find all connected PicoScope devices
connect_device	Connect to a specific device (by serial) or first available
get_device_info	Get details about connected device
disconnect_device	Disconnect from current device

Channel Configuration

Tool	Description
configure_channel	Set channel parameters (range, coupling, offset)
get_channel_config	Query current channel settings
set_timebase	Configure sampling rate (informational)

Triggering

Tool	Description
set_simple_trigger	Configure edge trigger (rising/falling/both)

Data Acquisition

Tool	Description
capture_block	Single snapshot capture with pre/post trigger samples
start_streaming	Begin continuous data capture
stop_streaming	End streaming mode
get_streaming_data	Retrieve latest streaming data

Analysis

Tool	Description
measure_frequency	Calculate signal frequency
measure_amplitude	Measure voltage (pk-pk, RMS, etc.)
measure_rise_time	Edge timing analysis
measure_pulse_width	Pulse characteristics
compute_fft	Frequency domain analysis
get_statistics	Signal statistics (min/max/mean/std)
measure_thd	Total Harmonic Distortion

Advanced

Tool	Description
set_signal_generator	Configure AWG output
stop_signal_generator	Disable signal generator
configure_math_channel	Channel operations (A+B, A-B, etc.)
export_waveform	Save data to file (CSV/JSON/NumPy)
configure_downsampling	Set downsampling mode

Example Usage with Claude

User: "Connect to the first PicoScope and measure the frequency on channel A"

Claude calls:
1. list_devices() -> finds available devices
2. connect_device() -> connects to first device
3. configure_channel(channel="A", enabled=true, voltage_range=5.0) -> enables channel A
4. set_simple_trigger(source="A", threshold_mv=0) -> sets auto-trigger
5. capture_block(pre_trigger_samples=1000, post_trigger_samples=1000) -> captures waveform
6. Returns captured data with time and voltage values

User can then analyze the returned data for frequency, or request additional captures.

Configuration

Typical Workflow

1. Connect: connect_device()
2. Configure Channels: configure_channel() for each channel
3. Set Trigger: set_simple_trigger()
4. Capture: capture_block() or start_streaming()
5. Analyze: Use measurement tools on captured data

Supported Hardware

• PS5000A Series (primary support)
• PS2000/3000/4000/6000 Series (planned)

Currently optimized for PS5000A. Other series will require device-specific implementations.

Development

Project Structure

picoscope_mcp/
├── src/picoscope_mcp/
│   ├── server.py          # FastMCP server
│   ├── device_manager.py  # Device abstraction
│   ├── models.py          # Data structures
│   ├── utils.py           # Helper functions
│   └── tools/             # MCP tool implementations
│       ├── discovery.py
│       ├── configuration.py
│       ├── acquisition.py
│       ├── analysis.py
│       └── advanced.py
└── tests/
    └── test_tools.py

Running Tests

uv run pytest

Adding Support for New Device Series

1. Update device_manager.py to detect device series
2. Import appropriate picosdk module (e.g., ps3000a)
3. Map device-specific constants and API calls
4. Handle series-specific capabilities

Troubleshooting

"PicoSDK not found" Error

Install PicoSDK C libraries for your platform (see Prerequisites).

"No device connected" Errors

1. Ensure PicoScope is connected via USB
2. Check device appears in system (Windows Device Manager, macOS System Information, Linux lsusb)
3. Verify PicoSDK drivers are installed
4. Try reconnecting the device

Channel Configuration Fails

• Check voltage range is supported: 0.02, 0.05, 0.1, 0.2, 0.5, 1, 2, 5, 10, 20V
• Verify channel exists (A-D for 4-channel models)

Capture Timeout

• Ensure trigger settings are appropriate for signal
• Try increasing auto-trigger timeout
• Check signal is within configured voltage range

Roadmap

• [x] Phase 1: Foundation - Device discovery, connection, PS5000A support
• [ ] Phase 2: Advanced acquisition - Streaming mode, advanced triggers
• [ ] Phase 3: Multi-device support - PS2000/3000/4000/6000 series
• [ ] Phase 4: Enhanced analysis - Real-time FFT, automated characterization
• [ ] Phase 5: Visualization - Web dashboard for waveform viewing

See PROJECT_PLAN.md for detailed architecture and development plans.

Contributing

Contributions are welcome! This project is in active development.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Clone your fork
git clone https://github.com/YOUR_USERNAME/picoscope_mcp.git
cd picoscope_mcp

# Install dependencies including dev tools
uv sync

# Run tests
uv run pytest

Areas for Contribution

• Support for additional PicoScope series (PS2000, PS3000, PS4000, PS6000)
• Streaming mode implementation
• Advanced trigger modes (pulse width, window, logic)
• Additional measurement algorithms
• Documentation and examples
• Test coverage
• Bug reports and fixes

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Note: This license allows commercial use but requires derivative works to remain open source under GPLv3.

Acknowledgments

• Pico Technology for the PicoSDK Python wrappers
• Anthropic for the Model Context Protocol
• Jeff Lowin for FastMCP
• The open source community

References

• PicoScope Programmers Guides
• picosdk-python-wrappers
• FastMCP Documentation
• Model Context Protocol Specification
• Claude Desktop MCP Setup

Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions