CUDA Quantum MCP Server

A comprehensive Model Context Protocol (MCP) server that provides quantum computing capabilities using NVIDIA's CUDA Quantum framework with GPU acceleration support.

🚀 Features

Quantum Circuit Building

• Create quantum kernels with parameterized circuits
• Apply quantum gates (H, X, Y, Z, CNOT, rotation gates, etc.)
• Build common circuits (Bell pairs, GHZ states, QFT)
• Visualize circuits in text format
• Manage quantum registers and qubit operations

Quantum Execution

• Sample quantum circuits with measurement statistics
• Compute expectation values of Hamiltonians
• Get quantum state vectors with amplitude analysis
• Run quantum algorithms with custom return values
• Variational optimization for quantum machine learning

Hardware Backend Integration

• Multiple simulators: CPU, GPU (cuQuantum), tensor networks
• Quantum hardware: IonQ, Quantinuum, Quantum Machines, and more
• GPU acceleration with NVIDIA CUDA support
• Target configuration with backend-specific parameters
• Connectivity testing for remote quantum processors

Advanced Features

• Python bridge for seamless CUDA Quantum integration
• Asynchronous execution for long-running quantum jobs
• Error mitigation and noise modeling
• Multi-GPU support for large-scale simulations
• Comprehensive logging and debugging tools

📦 Installation

Prerequisites

1. Node.js 18+ and npm
2. Python 3.8+ with pip
3. NVIDIA GPU (optional, for GPU acceleration)
4. CUDA Toolkit (optional, for GPU backends)

Install CUDA Quantum

# Install CUDA Quantum Python package
pip install cudaq

# For GPU support, ensure CUDA is properly installed
nvidia-smi  # Check NVIDIA driver
nvcc --version  # Check CUDA compiler

Install MCP Server

# Clone the repository
git clone <repository-url>
cd mcp-quantum

# Install Node.js dependencies
npm install

# Install Python dependencies
npm run python-setup

# Build TypeScript
npm run build

Environment Configuration

Copy the example environment file and configure:

cp .env.example .env

Edit .env with your settings:

# Server Configuration
SERVER_PORT=3000
NODE_ENV=production

# CUDA Quantum Configuration  
CUDAQ_PYTHON_PATH=/usr/local/bin/python3
CUDAQ_DEFAULT_TARGET=qpp-cpu
CUDAQ_LOG_LEVEL=info

# Python Bridge Timeout (milliseconds)
# Default: 300000 (5 minutes)
# Increase for complex operations or slower hardware
PYTHON_TIMEOUT=300000

# GPU Configuration
CUDA_VISIBLE_DEVICES=0
CUDAQ_ENABLE_GPU=true

# Hardware Provider API Keys (optional)
QUANTUM_MACHINES_API_KEY=your_api_key_here
IONQ_API_KEY=your_api_key_here

🏃‍♂️ Quick Start

1. Start the MCP Server

npm start

2. Connect via MCP Client

The server uses stdio transport for MCP communication:

# Example connection via Claude Desktop
# Add to your Claude Desktop config

3. Basic Quantum Circuit Example

// Create a Bell pair circuit
await mcp.callTool('create_quantum_kernel', {
  name: 'bell_pair',
  num_qubits: 2
});

// Apply Hadamard gate to qubit 0
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'bell_pair',
  gate_name: 'h',
  qubits: [0]
});

// Apply CNOT gate (controlled-X)
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'bell_pair', 
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

// Sample the circuit
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'bell_pair',
  shots: 1000
});

🔧 Available Tools

Quantum Circuit Tools

create_quantum_kernel

Create a new quantum kernel with specified qubits and parameters.

{
  "name": "my_kernel",
  "num_qubits": 4,
  "parameters": [
    {"name": "theta", "type": "float"},
    {"name": "angles", "type": "list[float]"}
  ]
}

apply_quantum_gate

Apply quantum gates to specific qubits with optional control qubits.

{
  "kernel_name": "my_kernel",
  "gate_name": "rx",
  "qubits": [0],
  "parameters": [1.57],
  "controls": [],
  "adjoint": false
}

Supported Gates:

• Single-qubit: h, x, y, z, s, t, rx, ry, rz
• Two-qubit: cx (CNOT), cy, cz, swap
• Multi-qubit: ccx (Toffoli), cswap (Fredkin)

create_common_circuit

Generate commonly used quantum circuits.

{
  "circuit_type": "ghz_state",
  "name": "ghz_3",
  "num_qubits": 3
}

Available Circuits:

• bell_pair: Maximally entangled two-qubit state
• ghz_state: Greenberger-Horne-Zeilinger state
• quantum_fourier_transform: QFT implementation
• hadamard_test: Hadamard test circuit

Quantum Execution Tools

sample_quantum_circuit

Execute quantum circuit and sample measurement results.

{
  "kernel_name": "bell_pair",
  "shots": 1000,
  "target": "qpp-gpu"
}

observe_hamiltonian

Compute expectation value of a Hamiltonian operator.

{
  "kernel_name": "my_kernel",
  "hamiltonian_terms": [
    {
      "paulis": ["Z", "Z"],
      "qubits": [0, 1],
      "coefficient": {"real": 1.0, "imag": 0.0}
    }
  ],
  "shots": 1000
}

get_quantum_state

Retrieve the quantum state vector from a circuit.

{
  "kernel_name": "my_kernel",
  "format": "amplitudes"
}

Hardware Backend Tools

set_quantum_target

Configure quantum execution target.

{
  "target": "qpp-gpu",
  "configuration": {
    "shots": 1000,
    "optimization_level": 2
  }
}

Available Targets:

Simulators:

• qpp-cpu: CPU state vector simulator
• qpp-gpu: GPU-accelerated simulator (cuQuantum)
• density-matrix-cpu: Density matrix simulator
• tensor-network: Tensor network simulator

Hardware Providers:

• ionq: IonQ quantum processors
• quantinuum: Quantinuum H-Series
• quantum_machines: Quantum Machines platform
• infleqtion: Infleqtion quantum processors

configure_gpu_acceleration

Enable/disable GPU acceleration for quantum simulations.

{
  "enable": true,
  "device_id": 0,
  "memory_limit": 8.0,
  "target": "qpp-gpu"
}

🧪 Examples

Example 1: Quantum Teleportation Circuit

// Create quantum teleportation circuit
await mcp.callTool('create_quantum_kernel', {
  name: 'teleportation',
  num_qubits: 3
});

// Prepare Bell pair (qubits 1,2)
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'h',
  qubits: [1]
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'x',
  qubits: [2],
  controls: [1]
});

// Teleportation protocol (qubit 0 -> qubit 2)
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'teleportation',
  gate_name: 'h',
  qubits: [0]
});

// Sample the results
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'teleportation',
  shots: 1000
});

Example 2: Variational Quantum Eigensolver (VQE)

// Create parameterized ansatz
await mcp.callTool('create_quantum_kernel', {
  name: 'vqe_ansatz',
  num_qubits: 2,
  parameters: [
    {"name": "theta1", "type": "float"},
    {"name": "theta2", "type": "float"}
  ]
});

// Build ansatz circuit
await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'vqe_ansatz',
  gate_name: 'ry',
  qubits: [0],
  parameters: ['theta1']  // Parameter reference
});

await mcp.callTool('apply_quantum_gate', {
  kernel_name: 'vqe_ansatz',
  gate_name: 'x',
  qubits: [1],
  controls: [0]
});

// Define H2 molecule Hamiltonian
const h2_hamiltonian = [
  {
    "paulis": ["Z", "I"],
    "qubits": [0, 1],
    "coefficient": {"real": -1.0523732, "imag": 0.0}
  },
  {
    "paulis": ["I", "Z"],
    "qubits": [0, 1], 
    "coefficient": {"real": -1.0523732, "imag": 0.0}
  },
  {
    "paulis": ["Z", "Z"],
    "qubits": [0, 1],
    "coefficient": {"real": -0.39793742, "imag": 0.0}
  }
];

// Compute expectation value
await mcp.callTool('observe_hamiltonian', {
  kernel_name: 'vqe_ansatz',
  hamiltonian_terms: h2_hamiltonian,
  parameters: {"theta1": 0.5, "theta2": 1.2}
});

Example 3: GPU-Accelerated Simulation

// Configure GPU acceleration
await mcp.callTool('configure_gpu_acceleration', {
  enable: true,
  device_id: 0,
  target: 'qpp-gpu'
});

// Create large quantum circuit
await mcp.callTool('create_quantum_kernel', {
  name: 'large_circuit',
  num_qubits: 20
});

// Apply random circuit
for (let i = 0; i < 20; i++) {
  await mcp.callTool('apply_quantum_gate', {
    kernel_name: 'large_circuit',
    gate_name: 'h',
    qubits: [i]
  });
}

// Add entangling gates
for (let i = 0; i < 19; i++) {
  await mcp.callTool('apply_quantum_gate', {
    kernel_name: 'large_circuit',
    gate_name: 'x',
    qubits: [i + 1],
    controls: [i]
  });
}

// Sample with GPU acceleration
await mcp.callTool('sample_quantum_circuit', {
  kernel_name: 'large_circuit',
  shots: 10000,
  target: 'qpp-gpu'
});

🔌 Hardware Provider Setup

IonQ Configuration

await mcp.callTool('set_quantum_target', {
  target: 'ionq',
  configuration: {
    api_key: process.env.IONQ_API_KEY,
    backend: 'simulator',  // or 'qpu'
    shots: 1000
  }
});

Quantinuum Setup

await mcp.callTool('set_quantum_target', {
  target: 'quantinuum',
  configuration: {
    api_key: process.env.QUANTINUUM_API_KEY,
    device: 'H1-1E',  // or other available devices
    shots: 1000
  }
});

Quantum Machines Setup

await mcp.callTool('set_quantum_target', {
  target: 'quantum_machines',
  configuration: {
    api_key: process.env.QUANTUM_MACHINES_API_KEY,
    url: 'https://api.quantum-machines.com',
    executor: 'qpu'  // or 'simulator'
  }
});

🐛 Troubleshooting

Common Issues

CUDA Quantum Import Error

Error: CUDA Quantum not available
Solution: pip install cudaq

GPU Not Detected

Error: CUDA device not found
Solution: 
1. Check nvidia-smi output
2. Install NVIDIA drivers
3. Set CUDA_VISIBLE_DEVICES=0

Python Bridge Timeout

Error: Python command timeout after Xms
Solution: 
1. Increase timeout with environment variable:
   export PYTHON_TIMEOUT=600000  # 10 minutes in milliseconds
2. Check Python path in .env:
   CUDAQ_PYTHON_PATH=/usr/local/bin/python3
3. Ensure CUDA Quantum is properly installed:
   python3 -c "import cudaq; print(cudaq.__version__)"
4. Check for Python process errors in logs

Note: The default timeout is 300,000ms (5 minutes). Complex quantum operations or slower hardware may require increasing this value via the PYTHON_TIMEOUT environment variable.

Debug Mode

Enable debug logging:

export LOG_LEVEL=debug
npm start

Testing Connection

// Test platform availability
await mcp.callTool('get_platform_info');

// Test backend connectivity
await mcp.callTool('test_backend_connectivity', {
  backend: 'qpp-gpu'
});

🧪 Testing

Run the test suite:

# Unit tests
npm test

# Integration tests  
npm run test:integration

# Coverage report
npm run test:coverage

📚 API Reference

MCP Tool Schema

All tools follow the MCP (Model Context Protocol) specification:

interface MCPTool {
  name: string;
  description: string;
  inputSchema: JSONSchema;
}

interface MCPToolResult {
  content: Array<{
    type: 'text' | 'image' | 'resource';
    text?: string;
    data?: string;
    uri?: string;
  }>;
  isError?: boolean;
}

Python Bridge API

The Python bridge provides direct access to CUDA Quantum:

class PythonBridge {
  // Kernel management
  createKernel(name: string, numQubits: number): Promise<PythonResponse>;
  applyGate(kernel: string, gate: string, qubits: number[]): Promise<PythonResponse>;
  
  // Execution
  sample(kernel: string, shots?: number): Promise<PythonResponse>;
  observe(kernel: string, hamiltonian: any[]): Promise<PythonResponse>;
  getState(kernel: string): Promise<PythonResponse>;
  
  // Configuration
  setTarget(target: string, config?: any): Promise<PythonResponse>;
}

🚀 Deployment

Docker Deployment

FROM nvidia/cuda:11.8-runtime-ubuntu22.04

# Install Node.js and Python
RUN apt-get update && apt-get install -y \\
    nodejs npm python3 python3-pip

# Install CUDA Quantum
RUN pip3 install cudaq

# Copy and build application
COPY . /app
WORKDIR /app
RUN npm install && npm run build

# Start server
CMD ["npm", "start"]

Production Configuration

# Production environment
NODE_ENV=production
MCP_SERVER_NAME=cuda-quantum-mcp-prod
CUDAQ_DEFAULT_TARGET=qpp-gpu
LOG_LEVEL=info

# GPU optimization
CUDA_VISIBLE_DEVICES=0,1,2,3
NVIDIA_VISIBLE_DEVICES=all

🤝 Contributing

1. Fork the repository
2. Create feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open Pull Request

Development Setup

# Install development dependencies
npm install

# Run in development mode
npm run dev

# Run linting
npm run lint

# Format code
npm run format

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• NVIDIA CUDA Quantum Team for the excellent quantum computing framework
• Anthropic for the Model Context Protocol specification
• Quantum computing community for inspiration and feedback

📞 Support

• Documentation: Full API docs
• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Built with ❤️ for the quantum computing community