QML-MCP: Quantum Machine Learning MCP Server
A Model Context Protocol (MCP) server for Quantum Machine Learning using Qiskit.
Features
- Quantum Circuit Execution: Run quantum circuits with configurable shots
- Quantum Kernel Computation: Compute quantum kernels for ML tasks
- Variational Quantum Classifier (VQC): Train quantum classifiers
- Model Evaluation: Evaluate trained quantum ML models
- Safety Limits: Configurable limits on qubits and shots
- Structured Logging: Comprehensive logging for debugging
- Error Handling: Detailed error messages with tracebacks
Installation
pip install -e .
For development:
pip install -e ".[dev]"
Requirements
- Python >= 3.10
- Qiskit >= 1.0.0, < 2.0.0 (Note: Qiskit Machine Learning 0.8.4 requires Qiskit 1.x)
- Qiskit Machine Learning >= 0.8.4
- MCP >= 0.9.0
Note on Qiskit Version: While Qiskit 2.0+ is available, Qiskit Machine Learning 0.8.4 (the latest stable version) requires Qiskit 1.x. This implementation uses Qiskit 1.4.5+ which provides all necessary quantum ML features.
Configuration
The server can be configured via environment variables:
QML_MCP_QUANTUM_MAX_SHOTS: Maximum shots per circuit (default: 100000)QML_MCP_QUANTUM_MAX_QUBITS: Maximum qubits allowed (default: 10)QML_MCP_QUANTUM_DEFAULT_SHOTS: Default shots for circuits (default: 1024)QML_MCP_LOG_LEVEL: Logging level (default: INFO)QML_MCP_ENABLE_DETAILED_ERRORS: Include detailed error traces (default: true)
Usage
Running the Server
python server.py
Available Tools
1. run_quantum_circuit
Execute a quantum circuit and get measurement results.
Parameters:
qasm(required): Quantum circuit in QASM3 formatshots(optional): Number of measurement shots (default: 1024)
Example:
{
"qasm": "OPENQASM 3.0;\ninclude \"stdgates.inc\";\nqubit[2] q;\nbit[2] c;\nh q[0];\ncx q[0], q[1];\nc[0] = measure q[0];\nc[1] = measure q[1];",
"shots": 1000
}
2. compute_quantum_kernel
Compute quantum kernel matrix for ML tasks using ZZ feature map.
Parameters:
train_data(required): Training data as 2D arraytest_data(optional): Test data as 2D arrayfeature_dimension(optional): Number of features
Example:
{
"train_data": [[0.1, 0.2], [0.3, 0.4], [0.5, 0.6]],
"test_data": [[0.7, 0.8]]
}
3. train_vqc
Train a Variational Quantum Classifier.
Parameters:
X_train(required): Training features as 2D arrayy_train(required): Training labels as 1D arrayfeature_dimension(optional): Number of featuresmax_iter(optional): Maximum optimization iterations (default: 100)
Example:
{
"X_train": [[0.1, 0.2], [0.2, 0.3], [0.8, 0.9], [0.9, 0.8]],
"y_train": [0, 0, 1, 1],
"max_iter": 50
}
Returns a base64-encoded trained model.
4. evaluate_model
Evaluate a trained quantum ML model.
Parameters:
model(required): Base64-encoded trained modelX_test(required): Test features as 2D arrayy_test(optional): Test labels for accuracy computation
Example:
{
"model": "gASVPAIAAA...",
"X_test": [[0.15, 0.25], [0.85, 0.95]],
"y_test": [0, 1]
}
Testing
Run tests:
pytest tests/
Run with coverage:
pytest --cov=. --cov-report=html tests/
Project Structure
qml-mcp/
├── server.py # Main MCP server
├── config.py # Configuration with Pydantic
├── qml/ # Quantum ML utilities
│ ├── __init__.py
│ └── utils.py # Core QML functions
├── tools/ # Additional tools
├── resources/ # MCP resources
├── prompts/ # Prompt templates
├── tests/ # Test suite
│ ├── test_config.py
│ └── test_qml_utils.py
└── pyproject.toml # Project metadata
Safety and Limits
The server implements several safety mechanisms:
- Qubit Limits: Maximum number of qubits per circuit (default: 10)
- Shot Limits: Maximum measurement shots (default: 100000)
- Input Validation: All inputs are validated before processing
- Error Handling: Comprehensive error messages with optional tracebacks
License
MIT License - see LICENSE file for details.