Skip to main content
Glama

qudi MCP Integration

by dirkenglund

šŸ”¬ qudi MCP Integration

Model Context Protocol (MCP) integration for qudi quantum photonics experiments

Enable natural language control of quantum experiments through Claude Desktop!

MIT License Python 3.8+ 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 → live progression

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

  • safety.py: Safety system and runlevel management

  • tools/: Tool implementations (instruments, measurements, safety)

  • claude_config/: Claude Desktop configuration templates

Safety System

Runlevels

  • dry-run (default): Simulation only, no hardware interaction

  • sim: Realistic simulation with hardware-like responses

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

  1. Implement in appropriate tools/ module

  2. Register in qudi_mcp_server.py tool list

  3. Add safety validation for parameters

  4. Test thoroughly in dry-run mode

  5. 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

  1. Dry-run: Logic validation without hardware

  2. Simulation: Realistic behavior testing

  3. Hardware: Real instrument validation (when available)

  4. Safety: Verify all safety mechanisms

  5. 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_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

  1. Check logs: MCP server logs to stderr

  2. Test tools directly: Run python qudi_mcp_server.py

  3. Validate config: Check Claude Desktop config file syntax

  4. Start simple: Begin with station.info and safety.check_interlocks

Contributing

This integration is part of the MIT QPG development branch. To contribute:

  1. Fork the repository

  2. Create feature branches from dev/llm-mcp-automation

  3. Follow safety-first development practices

  4. Include comprehensive tests

  5. 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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/dirkenglund/qudi-mcp-integration'

If you have feedback or need assistance with the MCP directory API, please join our Discord server