README.md•9.86 kB
# PicoScope MCP Server
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
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
```bash
# 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](https://www.picotech.com/downloads)
- **macOS**: Download PicoScope software package
- **Linux**: Install via package manager:
```bash
# Ubuntu/Debian
sudo apt-get install libps5000a libps4000a libps3000a libps2000a
```
2. **Python 3.11+** with uv package manager
### Install Dependencies
```bash
# Clone or navigate to the project directory
cd picoscope_mcp
# Install dependencies
uv sync
```
## Usage
### Running the Server
```bash
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`
```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
```bash
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](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
```bash
# 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](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](https://github.com/picotech/picosdk-python-wrappers)
- **Anthropic** for the [Model Context Protocol](https://modelcontextprotocol.io/)
- **Jeff Lowin** for [FastMCP](https://github.com/jlowin/fastmcp)
- The open source community
## References
- [PicoScope Programmers Guides](https://www.picotech.com/library/oscilloscopes)
- [picosdk-python-wrappers](https://github.com/picotech/picosdk-python-wrappers)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
- [Claude Desktop MCP Setup](https://docs.claude.com/en/docs/model-context-protocol)
## Contact
- **Issues**: [GitHub Issues](https://github.com/markuskreitzer/picoscope_mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/markuskreitzer/picoscope_mcp/discussions)