markuskreitzer/picoscope_mcp

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

Channel Configuration

Triggering

Data Acquisition

Analysis

Advanced

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

• 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 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 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