🔬 qudi MCP Integration
Model Context Protocol (MCP) integration for qudi quantum photonics experiments
Enable natural language control of quantum experiments through Claude Desktop!
🚀 Quick Start
1. Installation Options
📋 Standalone Mode (Recommended for Testing)
# Clone this repository
git clone https://github.com/dirkenglund/qudi-mcp-integration.git
cd qudi-mcp-integration
# Install minimal dependencies (simulation only)
pip install -r requirements-standalone.txt
🖼️ With Plot Extraction Capabilities
# Install standalone + plot extraction
pip install -r requirements-standalone.txt
pip install -r requirements-plot-extraction.txt
🔬 Full qudi Integration (For Hardware Control)
# For real quantum hardware control
pip install -r requirements-full.txt
# Additional setup required:
# 1. Install qudi-core separately
# 2. Configure hardware drivers
# 3. Set up measurement modules
2. Configure Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"qudi-mcp": {
"command": "/opt/homebrew/bin/python3",
"args": ["/path/to/qudi-mcp-integration/simple_mcp_server.py"],
"env": {
"PYTHONPATH": "/path/to/qudi-mcp-integration",
"QUDI_MCP_LOG_LEVEL": "INFO"
}
}
}
}
3. Test with Claude Desktop
Restart Claude Desktop and try:
"Get qudi station information"
Example Commands:
- "Start a photoluminescence scan from 630-650 nm"
- "Check all safety interlocks before measurement"
- "Can I safely set laser power to 5 milliwatts?"
Features
🛡️ Safety First
- Runlevels:
dry-run→sim→liveprogression - Parameter Validation: All values checked against safety limits
- Emergency Stop: Immediate halt capability
- Interlocks: Critical system monitoring
🔧 Instrument Control
- List and load qudi instruments
- Get/set parameters with safety validation
- Real-time status monitoring
- Simulated operation for safe testing
📊 Measurement Execution
- Available modules: PL scan, gate sweep, resonance scan, time trace, 2D maps
- Progress monitoring and data acquisition
- Configurable measurement parameters
- Data export capabilities
🤖 LLM Integration
- Natural language command processing
- Contextual tool suggestions
- Comprehensive error reporting
- Audit logging for all operations
🖼️ Plot Extraction (Optional)
- RKHS Spline Projection - Mathematical smoothing using reproducing kernel Hilbert spaces
- Computer Vision - Extract data points from scientific plots and graphs
- Spectrum Analysis - Advanced processing for spectroscopy data
- Multiple Formats - Support for PNG, JPG, TIFF, and other image formats
- Quantum Data - Optimized for photoluminescence and transport measurements
Plot Extraction Commands:
- "Extract data from this plot image: /path/to/spectrum.png"
- "Analyze spectrum with RKHS smoothing using epsilon 0.05"
- "What plot extraction capabilities are available?"
Architecture
Claude ←→ MCP ←→ qudi_mcp_server ←→ qudi ←→ Instruments
↓
Safety System
Runlevel Control
Parameter Validation
Core Components
qudi_mcp_server.py: Main MCP server and tool routersafety.py: Safety system and runlevel managementtools/: Tool implementations (instruments, measurements, safety)claude_config/: Claude Desktop configuration templates
Safety System
Runlevels
dry-run(default): Simulation only, no hardware interactionsim: Realistic simulation with hardware-like responseslive: Real hardware control (requires approval + safety checks)
Built-in Limits
- Laser power: 0-10 mW
- Gate voltages: ±2.0 V
- Bias voltages: ±1.0 V
- Temperature: 0.01-300 K
- Magnetic field: ±9.0 T
- Measurement time: 0.001-3600 s
Emergency Procedures
All emergency stop triggers:
- Halt all running measurements
- Force runlevel to
dry-run - Log incident with timestamp
- Require manual reset with confirmation
Usage Examples
System Status
# Check system status
→ Get qudi station information
# Response: runlevel, loaded instruments, active measurements, safety status
Instrument Control
# List instruments
→ List available qudi instruments
# Load an instrument
→ Load the laser_controller instrument
# Set parameter safely
→ Set laser power to 2.5 mW
Measurements
# Start a measurement
→ Start a photoluminescence scan from 630 to 650 nm with 0.5 second integration
# Check progress
→ What's the status of running measurements?
# Get results
→ Get the measurement data for the PL scan
Safety Operations
# Check safety systems
→ Check all safety interlocks
# Change runlevel (when ready for hardware)
→ Set runlevel to sim mode for realistic testing
# Emergency procedures
→ Emergency stop all operations
Development Status
✅ Completed (Phase 1)
- MCP server framework
- Safety system with runlevels and limits
- Tool architecture for instruments, measurements, safety
- Claude Desktop integration
- Comprehensive simulation mode
- Documentation and setup guides
🚧 In Progress (Phase 2)
- qudi core integration
- Real instrument driver connections
- Hardware abstraction layer
- Live mode approval workflows
📋 Planned (Phase 3)
- Advanced measurement protocols
- Data analysis tool integration
- Multi-user access control
- Web-based monitoring interface
File Structure
mcp_integration/
├── __init__.py # Package initialization
├── qudi_mcp_server.py # Main MCP server
├── safety.py # Safety and runlevel system
├── tools/ # MCP tool implementations
│ ├── __init__.py
│ ├── instrument_tools.py # Instrument control tools
│ ├── measurement_tools.py # Measurement execution tools
│ └── safety_tools.py # Safety and emergency tools
├── claude_config/ # Claude configuration templates
├── README.md # This file
└── requirements.txt # Python dependencies
Development Guidelines
Adding New Tools
- Implement in appropriate
tools/module - Register in
qudi_mcp_server.pytool list - Add safety validation for parameters
- Test thoroughly in dry-run mode
- Document in tool docstrings
Safety Requirements
- All write operations must validate parameters
- Critical operations need explicit approval in live mode
- Comprehensive error handling and logging required
- Emergency stop must work from any state
Testing Protocol
- Dry-run: Logic validation without hardware
- Simulation: Realistic behavior testing
- Hardware: Real instrument validation (when available)
- Safety: Verify all safety mechanisms
- Integration: End-to-end workflow testing
Troubleshooting
Common Issues
"MCP package not found"
pip install mcp
"Tool not found" errors
- Check tool registration in
qudi_mcp_server.py - Verify tool implementation in
tools/modules
Safety validation failures
- Check parameter values against limits in
safety.py - Use
safety.get_limitsto see current constraints
Claude Desktop not seeing tools
- Verify absolute paths in configuration file
- Restart Claude Desktop completely
- Check Python path and MCP server execution
Getting Help
- Check logs: MCP server logs to stderr
- Test tools directly: Run
python qudi_mcp_server.py - Validate config: Check Claude Desktop config file syntax
- Start simple: Begin with
station.infoandsafety.check_interlocks
Contributing
This integration is part of the MIT QPG development branch. To contribute:
- Fork the repository
- Create feature branches from
dev/llm-mcp-automation - Follow safety-first development practices
- Include comprehensive tests
- Update documentation for new features
Repository: https://github.com/dirkenglund/qudi-iqo-modules-QPG
Branch: dev/llm-mcp-automation
Documentation: See docs/LLM_MCP_INTEGRATION.md for full details