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 format
• shots (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 array
• test_data (optional): Test data as 2D array
• feature_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 array
• y_train (required): Training labels as 1D array
• feature_dimension (optional): Number of features
• max_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 model
• X_test (required): Test features as 2D array
• y_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.