---
title: QuantumArchitect MCP
emoji: ⚛️
colorFrom: indigo
colorTo: purple
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
license: mit
short_description: Quantum Circuit Architect & MCP Server for AI Agents
tags:
- building-mcp-track-enterprise
- building-mcp-track-consumer
- building-mcp-track-creative
- Google-Gemini-API
---
VIDEO: https://youtu.be/E1Ailx1X1YE
SOCIAL: https://www.linkedin.com/posts/nicolas-larenas_quantumarchitect-mcp-a-hugging-face-space-activity-7401024993893044225-RF-R?utm_source=share&utm_medium=member_desktop&rcm=ACoAADmu0wIBjvA0DVdHvqncNUVTEW72gbiGUps
# QuantumArchitect-MCP 🔬⚛️
A Python-based MCP (Model Context Protocol) Server for Quantum Circuit creation, validation, and evaluation. This serves as a "Quantum Logic Engine" that AI Agents can call upon to validate, score, and execute quantum logic.
## 🚀 Features
- **Circuit Creation**: Generate Bell States, GHZ States, QFT, Grover's Algorithm, and VQE Ansatz circuits
- **Circuit Validation**: Syntax checking, connectivity validation for real hardware, unitarity verification
- **Circuit Evaluation**: Statevector simulation, noise estimation, resource estimation
- **Circuit Scoring**: Complexity metrics, expressibility scores, hardware fitness evaluation
- **MCP Endpoints**: Full MCP protocol support for AI Agent integration
- **Hardware Profiles**: Support for IBM, Rigetti, and other quantum hardware topologies
## 📦 Installation
### For Hugging Face Spaces
This project is designed to run directly on Hugging Face Spaces. Simply clone and deploy!
### Local Installation
```bash
pip install -r requirements.txt
python app.py
```
## 🚀 Quick Start
### 1. Start the Application
```bash
python app.py
```
The app will start at `http://127.0.0.1:7861`
### 2. Build Your First Circuit
1. Open the web interface in your browser
2. Go to the "Circuit Builder" tab
3. Click the "H" button to add a Hadamard gate
4. Click "Simulate" to see the results
5. View the Bloch sphere visualization of the qubit state
### 3. Try a Bell State
1. Go to the "Templates" tab
2. Select "Bell State" from the dropdown
3. Click "Load Template"
4. Click "Simulate" to see entangled output (50/50 probabilities)
### 4. Validate a Circuit
1. Go to the "Validate" tab
2. Paste or enter QASM code
3. Select target hardware (e.g., "ibm_eagle")
4. Click "Validate" to check syntax, connectivity, and unitarity
## 🔧 Project Structure
```
QuantumArchitect-MCP/
├── app.py # Main entry point (Gradio + MCP)
├── requirements.txt # Dependencies
├── pyproject.toml # Project configuration
├── src/
│ ├── mcp_server/ # MCP Protocol handling
│ │ ├── server.py # MCP capabilities definition
│ │ ├── schemas.py # JSON schemas for I/O
│ │ └── context_provider.py # Resource providers
│ ├── core/ # Quantum engine core
│ │ ├── circuit_parser.py # QASM/circuit parsing
│ │ ├── dag_representation.py # Internal DAG model
│ │ └── exceptions.py # Custom exceptions
│ ├── plugins/ # Modular components
│ │ ├── creation/ # Circuit generation
│ │ ├── validation/ # Circuit validation
│ │ ├── evaluation/ # Circuit evaluation
│ │ └── scoring/ # Circuit scoring
│ └── data/ # Knowledge base
│ ├── hardware_profiles/ # Hardware topology configs
│ └── reference_circuits/ # Standard algorithm references
└── tests/ # Test suite
```
## 🎯 MCP Endpoints
### Creation Tools
- `create_bell_state`: Generate a 2-qubit Bell state circuit
- `create_ghz_state`: Generate an N-qubit GHZ state
- `create_qft`: Generate Quantum Fourier Transform circuit
- `create_grover`: Generate Grover's search algorithm
- `create_vqe_ansatz`: Generate VQE variational ansatz
### Validation Tools
- `validate_syntax`: Check circuit syntax validity
- `validate_connectivity`: Verify hardware topology compatibility
- `validate_unitarity`: Check if circuit is properly unitary
### Evaluation Tools
- `simulate_statevector`: Get ideal simulation results
- `estimate_noise`: Estimate circuit noise accumulation
- `estimate_resources`: Calculate required shots and resources
### Scoring Tools
- `score_complexity`: Get circuit depth, gate count, width
- `score_expressibility`: Evaluate VQC expressibility (QML)
- `score_hardware_fitness`: Rate circuit for specific hardware
## 🖥️ Usage
### Web Interface
Access the Gradio UI at the deployed URL or `http://localhost:7860` for local runs.
### MCP Integration
Connect your AI Agent to the MCP endpoints:
```python
# Example: Claude Desktop configuration
{
"mcpServers": {
"quantum-architect": {
"url": "https://your-space.hf.space/mcp"
}
}
}
```
## 📚 Learning Path Integration
This tool follows the "Zero to Hero" quantum computing curriculum:
1. **Level 0 (Beginner)**: Use creation templates (Bell, GHZ states)
2. **Level 1 (Practitioner)**: Validate circuits against real hardware
3. **Level 2 (Advanced)**: Evaluate noise and optimize for NISQ devices
4. **Level 3 (PhD/Hero)**: Score expressibility and develop new algorithms
## 🤖 AI Agent Integration
### Available MCP Tools
| Tool | Description | Parameters |
|------|-------------|------------|
| `mcp_create_circuit` | Create from template | `template_name`, `num_qubits`, `parameters_json` |
| `mcp_parse_qasm` | Parse OpenQASM code | `qasm_code`, `qasm_version` |
| `mcp_build_circuit` | Build custom circuit | `num_qubits`, `gates_json`, `measurements_json` |
| `mcp_validate_circuit` | Validate circuit | `qasm_code`, `hardware_target`, `check_connectivity`, `check_unitary` |
| `mcp_check_hardware` | Check hardware compatibility | `qasm_code`, `hardware_name` |
| `mcp_simulate` | Simulate circuit | `qasm_code`, `shots`, `include_statevector`, `noise_model` |
| `mcp_get_statevector` | Get ideal statevector | `qasm_code` |
| `mcp_estimate_fidelity` | Estimate hardware fidelity | `qasm_code`, `hardware_name` |
| `mcp_score_circuit` | Score circuit | `qasm_code`, `hardware_name` |
| `mcp_compare_circuits` | Compare multiple circuits | `circuits_json`, `hardware_name` |
| `mcp_get_gate_info` | Gate documentation | `gate_name` |
| `mcp_get_algorithm_info` | Algorithm explanation | `algorithm_name` |
| `mcp_list_hardware` | List hardware profiles | - |
| `mcp_list_templates` | List circuit templates | - |
| `mcp_get_learning_path` | Get learning resources | `level` |
### Supported Hardware Profiles
- **IBM Eagle** (127 qubits, heavy-hex topology)
- **Rigetti Aspen** (80 qubits, octagonal topology)
- **IonQ Aria** (25 qubits, all-to-all connectivity)
### Circuit Templates
- `bell_state` - Maximally entangled 2-qubit state
- `ghz_state` - N-qubit GHZ entangled state
- `w_state` - N-qubit W state
- `superposition` - Uniform superposition
- `qft` - Quantum Fourier Transform
- `grover` - Grover's search algorithm
- `vqe` - VQE variational ansatz
- `qaoa` - QAOA optimization circuit
## 🧪 Running Tests
```bash
pytest tests/ -v
```
## 📄 License
MIT License - See LICENSE file for details.
## 🙏 Acknowledgments
Built with:
- [Gradio](https://gradio.app/) - UI and MCP integration
- [Qiskit](https://qiskit.org/) - Quantum computing framework
- [Pydantic](https://pydantic.dev/) - Data validation
