Psi-MCP: Advanced Quantum Systems MCP Server

The most comprehensive quantum physics MCP server for complex open and closed quantum systems calculations

🌟 Overview

Psi-MCP is an advanced Model Context Protocol (MCP) server specifically designed for quantum systems analysis and simulation. It provides comprehensive tools for quantum computing, quantum chemistry, many-body physics, quantum machine learning, and quantum field theory calculations.

Key Features

🔬 Quantum Circuit Operations: Create, simulate, optimize, and visualize quantum circuits
⚛️ Open Quantum Systems: Solve master equations, analyze decoherence, compute steady states
🧪 Quantum Chemistry: Molecular Hamiltonians, VQE, electronic structure calculations
🔗 Many-Body Physics: DMRG, tensor networks, phase transitions, correlation functions
🤖 Quantum Machine Learning: QNNs, variational classifiers, quantum kernels
🌊 Quantum Field Theory: Field quantization, path integrals, RG flow, anomalies
📊 Advanced Visualization: Bloch spheres, density matrices, Wigner functions
🚀 Smithery Compatible: Easy deployment and integration

🛠 Installation

Prerequisites

Python 3.11 or higher
Docker (for containerized deployment)
Git

Core vs Optional Dependencies

Core Dependencies (always installed):

FastAPI, Uvicorn (MCP server framework)
Qiskit, Cirq, PennyLane (quantum computing)
QuTiP (open quantum systems)
OpenFermion (quantum chemistry)
NumPy, SciPy, Matplotlib (numerical computing)

Optional Dependencies (install separately if needed):

PySCF (advanced quantum chemistry)
TensorFlow Quantum (quantum ML)
NetKet (neural quantum states)
Additional quantum libraries

Quick Start with Smithery

# Install via Smithery CLI npx @smithery/cli install psi-mcp --client cursor # Or deploy via GitHub integration git clone https://github.com/manasp21/Psi-MCP.git cd Psi-MCP # Push to your GitHub repository and connect to Smithery

Local Development

# Clone the repository git clone https://github.com/manasp21/Psi-MCP.git cd Psi-MCP # Install dependencies pip install -r requirements.txt # Run the server python src/server.py

Docker Deployment

# Build the container docker build -t psi-mcp . # Run with configuration docker run -p 8000:8000 \ -e computing_backend=simulator \ -e max_qubits=20 \ -e precision=double \ psi-mcp

🔧 Configuration

Smithery Configuration

Configure via the Smithery dashboard or query parameters:

computing_backend: "simulator" # qasm_simulator, statevector_simulator max_qubits: 20 # Maximum qubits (1-30) precision: "double" # single, double, extended enable_gpu: false # GPU acceleration timeout_seconds: 300 # Calculation timeout memory_limit_gb: 4 # Memory limit

Environment Variables

PORT=8000 # Server port HOST=0.0.0.0 # Server host COMPUTING_BACKEND=simulator # Default backend MAX_QUBITS=20 # Default max qubits

🚀 Usage

Quantum Circuit Operations

Create Quantum Circuits

# Create a Bell state circuit create_quantum_circuit( num_qubits=2, circuit_type="bell", backend="qasm_simulator" ) # Create a GHZ state create_quantum_circuit( num_qubits=4, circuit_type="ghz", backend="statevector_simulator" ) # Create quantum Fourier transform create_quantum_circuit( num_qubits=3, circuit_type="qft", backend="simulator" )

Simulate Circuits

# Simulate with measurements simulate_quantum_circuit( circuit_definition="circuit_1", shots=1024, backend="qasm_simulator" ) # Get statevector simulate_quantum_circuit( circuit_definition="circuit_2", shots=1, backend="statevector_simulator" )

Optimize Circuits

# Optimize for specific backend optimize_quantum_circuit( circuit_definition="circuit_1", optimization_level=2, target_backend="qasm_simulator" )

Open Quantum Systems

Master Equation Solving

# Solve Lindblad master equation solve_master_equation( hamiltonian="pauli_z", collapse_operators="spontaneous_emission", initial_state="excited", time_span="0,10,100", solver_method="mesolve" ) # Analyze decoherence analyze_decoherence( system_hamiltonian="pauli_x", environment_coupling="dephasing", temperature=0.1, analysis_type="dephasing" )

Quantum Chemistry

Molecular Calculations

# Generate molecular Hamiltonian generate_molecular_hamiltonian( molecule="H2", basis="sto-3g", charge=0, multiplicity=1 ) # Run VQE for electronic structure vqe_chemistry( molecule="H2O", basis="6-31g", ansatz="uccsd", optimizer="cobyla" ) # Simulate chemical reactions simulate_chemical_reaction( reactants=["H2", "O2"], products=["H2O"], method="vqe" )

Quantum Algorithms

Shor's Algorithm

# Factor integers shors_algorithm( N=15, backend="qasm_simulator", shots=1024 )

Grover's Search

# Search marked items grovers_search( marked_items=[3, 7], search_space_size=16, backend="simulator" )

VQE Optimization

# Variational quantum eigensolver vqe_optimization( hamiltonian="ising", ansatz_type="ry", optimizer="cobyla", max_iterations=100 )

Many-Body Physics

DMRG Simulations

# Run DMRG for spin chains dmrg_simulation( hamiltonian_type="heisenberg", system_size=20, bond_dimension=100, max_sweeps=10 ) # Phase transition analysis phase_transition_analysis( model_type="ising", parameter_range=[0.0, 2.0], n_points=20, system_size=16 )

Quantum Machine Learning

Neural Networks

# Train quantum neural network quantum_neural_network( input_data=[[0.1, 0.2], [0.3, 0.4]], labels=[0, 1], n_qubits=4, n_layers=2, epochs=50 ) # Variational classifier variational_classifier( training_data=train_X, training_labels=train_y, test_data=test_X, ansatz_type="hardware_efficient" )

Visualization

Quantum States

# Bloch sphere visualization visualize_quantum_state( state_definition="superposition", visualization_type="bloch_sphere" ) # Density matrix plot visualize_quantum_state( state_definition="bell", visualization_type="density_matrix" ) # Wigner function visualize_quantum_state( state_definition="coherent", visualization_type="wigner_function" )

📚 API Reference

Core Tools

Tool Name	Description	Parameters
`create_quantum_circuit`	Create quantum circuits	`num_qubits` , `circuit_type` , `backend`
`simulate_quantum_circuit`	Simulate circuits	`circuit_definition` , `shots` , `backend`
`solve_master_equation`	Solve open system dynamics	`hamiltonian` , `collapse_operators` , `initial_state`
`vqe_optimization`	Variational quantum eigensolver	`hamiltonian` , `ansatz_type` , `optimizer`
`dmrg_simulation`	Many-body simulations	`hamiltonian_type` , `system_size` , `bond_dimension`
`quantum_neural_network`	Train QNNs	`input_data` , `labels` , `n_qubits` , `n_layers`

Supported Backends

Qiskit: qasm_simulator, statevector_simulator, unitary_simulator
Cirq: cirq_simulator
PennyLane: default.qubit, default.qubit.torch

Circuit Types

empty: Empty circuit
bell: Bell state preparation
ghz: GHZ state preparation
qft: Quantum Fourier transform
random: Random circuit

🏗 Architecture

Psi-MCP/ ├── src/ │ ├── server.py # Main MCP server │ └── quantum/ # Quantum modules │ ├── __init__.py # Backend initialization │ ├── circuits.py # Circuit operations │ ├── systems.py # Open quantum systems │ ├── algorithms.py # Quantum algorithms │ ├── chemistry.py # Quantum chemistry │ ├── many_body.py # Many-body physics │ ├── field_theory.py # Quantum field theory │ ├── ml.py # Quantum ML │ ├── visualization.py # Visualization tools │ └── utils.py # Utility functions ├── tests/ # Test suite ├── docs/ # Documentation ├── smithery.yaml # Smithery configuration ├── Dockerfile # Container configuration ├── requirements.txt # Python dependencies └── README.md # This file

🧪 Examples

Complete Workflow Example

# 1. Create and simulate a quantum circuit circuit_result = create_quantum_circuit( num_qubits=3, circuit_type="ghz", backend="qasm_simulator" ) # 2. Simulate the circuit simulation_result = simulate_quantum_circuit( circuit_definition=circuit_result['id'], shots=1000, backend="qasm_simulator" ) # 3. Visualize the results plot_result = plot_measurement_results( counts=simulation_result['counts'], title="GHZ State Measurement" ) # 4. Analyze entanglement entropy = calculate_entanglement_entropy( circuit_definition=circuit_result['id'], subsystem_size=1 )

Quantum Chemistry Workflow

# 1. Generate molecular Hamiltonian hamiltonian = generate_molecular_hamiltonian( molecule="H2", basis="sto-3g" ) # 2. Run VQE calculation vqe_result = vqe_chemistry( molecule="H2", basis="sto-3g", ansatz="uccsd" ) # 3. Compute molecular properties properties = compute_molecular_properties( molecule="H2", method="hf", basis="sto-3g" )

🔬 Advanced Features

Custom Hamiltonians

# Define custom spin chain solve_master_equation( hamiltonian=json.dumps([[1, 0], [0, -1]]), collapse_operators="custom_operators", initial_state="custom_state" )

GPU Acceleration

# Enable GPU support configure_server( enable_gpu=True, computing_backend="gpu_simulator" )

Parallel Processing

# Parallel circuit simulation simulate_circuits_parallel( circuit_definitions=["circuit_1", "circuit_2", "circuit_3"], shots=1000 )

📊 Performance

Benchmarks

Operation	System Size	Execution Time	Memory Usage
Circuit Simulation	20 qubits	~2s	~100MB
VQE Optimization	H2O molecule	~30s	~200MB
DMRG Calculation	50 sites	~60s	~500MB
QNN Training	100 samples	~45s	~150MB

Scaling

Quantum Circuits: Up to 30 qubits (simulator dependent)
Many-Body Systems: Up to 100 sites with DMRG
Molecular Systems: Up to 20 orbitals with VQE
ML Training: Up to 1000 samples efficiently

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone and install development dependencies git clone https://github.com/manasp21/Psi-MCP.git cd Psi-MCP pip install -r requirements.txt pip install -e .[dev] # Run tests pytest tests/ # Format code black src/ tests/ isort src/ tests/ # Type checking mypy src/

📄 License

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

🙏 Acknowledgments

Qiskit Team for quantum computing framework
QuTiP Developers for open quantum systems tools
PennyLane Team for quantum machine learning
OpenFermion Contributors for quantum chemistry tools
Smithery Platform for MCP server hosting

📞 Support

GitHub Issues: Report bugs or request features
Documentation: Full API documentation
Examples: Jupyter notebooks with examples

🗺 Roadmap

v1.1.0 (Next Release)

ITensor integration for tensor networks
NetKet support for neural quantum states
Advanced error mitigation tools
Quantum error correction codes

v1.2.0 (Future)

Hardware backend support (IBM, Google, IonQ)
Advanced visualization dashboard
Quantum advantage benchmarks
Multi-user collaboration features

Built with ❤️ for the quantum computing community

🌟 Star us on GitHub | 📖 Read the Docs | 🚀 Deploy on Smithery