š¬ 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)
š¼ļø With Plot Extraction Capabilities
š¬ Full qudi Integration (For Hardware Control)
2. Configure Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json
:
3. Test with Claude Desktop
Restart Claude Desktop and try:
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
ālive
progressionParameter 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
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
Instrument Control
Measurements
Safety 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
Development Guidelines
Adding New Tools
Implement in appropriate
tools/
moduleRegister in
qudi_mcp_server.py
tool listAdd 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"
"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_limits
to 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.info
andsafety.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
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
Enables natural language control of quantum photonics experiments through the qudi framework. Supports safe instrument control, measurement execution, and safety system management with built-in runlevel protection and parameter validation.