Quantum ZX-Calculus MCP Server
Categorical quantum circuit optimization using symmetric monoidal category theory
Transform quantum circuits into ZX-diagrams with deterministic simplification strategies and educational visualizations. Built on the ZX-calculus framework (Coecke & Duncan, 2008-2017) with a cost-optimized architecture achieving 60-85% LLM cost reduction.
Overview
The ZX-calculus is a graphical language for quantum computing based on symmetric monoidal categories (SMCs), where quantum circuits are represented as string diagrams with colored "spiders" (nodes) and wires. This MCP server provides:
- Circuit → ZX-diagram conversion (QASM/Qiskit → spider notation)
- Deterministic simplification (spider fusion, phase cancellation, Hadamard removal)
- Optimization strategy selection (Clifford simplification, T-count reduction, measurement-based)
- Educational synthesis (natural language explanations + SVG visualizations)
Why Categorical?
The ZX-calculus exploits compositional semantics: quantum gates compose like morphisms in a category, with:
- Serial composition: Gate sequencing (type-safe: outputs must match inputs)
- Parallel composition: Tensor product (multi-qubit operations)
- Rewrite rules: Semantics-preserving transformations (proven sound + complete)
This categorical structure enables deterministic optimizations (0 LLM tokens) for 60-85% of the workflow, with LLM synthesis reserved for explanation and customization.
Architecture: 4-Layer Categorical Hierarchy
Layer 1: Foundation (Pure Taxonomy)
Cost: 0 tokens (static lookups)
# Deterministic quantum gate → ZX spider mapping
QUANTUM_GATE_TAXONOMY = {
"h": QuantumGate(primary_spider=H_BOX, phase=0.0, is_clifford=True),
"t": QuantumGate(primary_spider=Z_SPIDER, phase=0.25, is_clifford=False),
"cx": QuantumGate(primary_spider=Z_SPIDER, phase=0.0, is_clifford=True),
# ... 15+ gates with ZX equivalents
}
Provides:
- Complete gate taxonomy (Clifford, Clifford+T, measurement operators)
- Spider types (Z/X/H) and phase parameters
- Basis specifications (computational, Hadamard)
- Spider fusion rules (bialgebra structure)
Layer 2: Structure (Deterministic Operations)
Cost: 0 tokens (pure computation)
# Parse circuit, analyze properties, select strategy
circuit = parse_qasm_circuit(qasm_code) # 0 tokens
analysis = analyze_circuit(circuit) # 0 tokens
zx_diagram = circuit_to_zx_diagram(circuit) # 0 tokens
strategy = select_simplification_strategy(...) # 0 tokens
Provides:
- Circuit parsing (QASM → gate sequence)
- Property analysis (T-count, entanglement, Clifford depth)
- ZX-diagram construction (spiders + wires + phases)
- Rewrite strategy selection (based on circuit properties)
Layer 3: Relational (Compositional Rules)
Cost: 0 tokens (categorical logic)
Implements ZX-calculus rewrite rules:
- Spider fusion: Adjacent same-color spiders merge (phases add mod 2π)
- Phase cancellation: Phases summing to 2π disappear
- Hadamard removal: H · H = identity
- Color change: H · Z · H = X (basis transformation)
Layer 4: Contextual (LLM Synthesis)
Cost: ~100-200 tokens (single LLM call)
LLM synthesizes:
- Natural language circuit explanations
- Custom optimization strategies
- Educational step-by-step visualizations
- Domain-specific simplifications
Cost Optimization
Traditional approach: LLM for entire workflow (~500-1000 tokens)
User query → LLM analyzes → LLM parses → LLM optimizes → LLM visualizes
Categorical approach: Deterministic layers + targeted synthesis (~100-200 tokens)
User query → Parse (0) → Analyze (0) → ZX convert (0) → Select strategy (0) → LLM synthesizes explanation (100-200)
Result: 60-85% cost reduction by encoding domain expertise as categorical structure rather than prompt engineering.
Features
Circuit Conversion
- QASM 2.0 support: Standard quantum assembly language
- Qiskit compatibility: Python quantum framework integration
- Gate coverage: 15+ gates (Pauli, Clifford, T, CNOT, CZ, SWAP)
- Multi-qubit circuits: Arbitrary qubit counts with entanglement tracking
Simplification Strategies
# Automatically select optimization based on circuit analysis
strategy = select_simplification_strategy(
analysis=circuit_analysis,
desired_outcome="t_count_reduction" # or "clifford_simplification", "educational"
)
Available strategies:
- Clifford simplification: Reduce Clifford gate count (stabilizer circuits)
- T-count reduction: Minimize T gates (critical for fault tolerance)
- Measurement-based: Convert to measurement-based quantum computation
- Educational: Step-by-step with explanations at each transformation
Analysis & Metrics
stats = get_circuit_statistics(circuit)
# Returns:
# - Gate composition (Clifford vs T counts)
# - Entanglement score (0-1 estimate)
# - Clifford depth, estimated T-count
# - Recommended optimization strategies
Educational Visualization
- SVG string diagram generation
- Step-by-step rewrite sequences
- Natural language explanations of each transformation
- LaTeX-ready mathematical notation
Installation
# Clone repository
git clone https://github.com/yourusername/quantum-zx-mcp.git
cd quantum-zx-mcp
# Install with development dependencies
pip install -e ".[dev]"
# Run tests
./tests/run_tests.sh
Deploy to FastMCP Cloud
fastmcp deploy
Quick Start
Example 1: Simple Circuit Analysis
from quantum_zx_calculus import parse_qasm_circuit, analyze_circuit
qasm = """
OPENQASM 2.0;
qreg q[2];
h q[0];
cx q[0], q[1];
"""
circuit = parse_qasm_circuit(qasm)
analysis = analyze_circuit(circuit)
print(f"Total gates: {analysis.total_gates}")
print(f"Clifford gates: {analysis.clifford_gates}")
print(f"Is Clifford-only: {analysis.is_clifford_only}")
print(f"Recommended strategies: {[s.value for s in analysis.recommended_strategies]}")
Output:
Total gates: 2
Clifford gates: 2
Is Clifford-only: True
Recommended strategies: ['clifford_simplification', 'educational']
Example 2: ZX-Diagram Conversion
from quantum_zx_calculus import circuit_to_zx_diagram
zx_diagram = circuit_to_zx_diagram(circuit)
print(f"Spiders: {len(zx_diagram.spiders)}")
print(f"Wires: {len(zx_diagram.wires)}")
print(f"Phases: {zx_diagram.phases}")
Output:
Spiders: 4
Wires: 3
Phases: {0: 0.0, 1: 0.0, 2: 0.0, 3: 0.0}
Example 3: Claude Synthesis (via MCP)
User: "Analyze this Bell state preparation circuit and explain what it does"
MCP Server:
1. Parses QASM → 2-qubit circuit (H, CNOT)
2. Converts to ZX → 4 spiders, 3 wires
3. Analyzes → Clifford-only, creates entanglement
4. Passes structured data to Claude
LLM (e.g., Claude) synthesizes:
"This circuit creates a Bell state (|Φ+⟩), a maximally entangled state.
The Hadamard on qubit 0 creates superposition (|0⟩+|1⟩)/√2, then the CNOT
entangles it with qubit 1. In ZX-calculus, this appears as a Z-spider
(Hadamard) connected to an X-spider (CNOT control/target), forming the
characteristic 'cup' structure of entanglement."
Theoretical Foundation
Structural Isomorphism: Manufacturing vs Quantum Circuits
Categorical Correspondence Table
| NIST Process Planning | ZX-Calculus MCP Server | Categorical Structure |
|---|---|---|
| Machine operations | Quantum gates (H, T, CNOT, etc.) | Atomic morphisms in category |
| Production line sequences | Circuit gate sequences | Serial composition (type-safe) |
| Parallel factory operations | Multi-qubit tensor operations | Parallel composition (⊗) |
| Task decomposition | Gate → Spider conversion | Functorial mapping F: Gates → Spiders |
| Process constraints | Type matching (outputs → inputs) | Monoidal category coherence |
| Resource routing | Wire connectivity in ZX-diagram | String diagram topology |
| Factory-level planning | Optimization strategy selection | Higher-order morphism composition |
| Supply chain coordination | Educational synthesis & explanation | Contextual interpretation layer |
| Process validation | Semantics-preserving rewrites | Category-theoretic soundness proofs |
| Cost optimization | T-count reduction, Clifford simplification | Resource-aware functor selection |
| Multi-scale hierarchy | 4-layer architecture (Foundation → Contextual) | Compositional abstraction levels |
| Identity processes | Identity gates (bare wires) | Identity morphisms in category |
Key Insight
Both systems exhibit symmetric monoidal category (SMC) structure where:
- Objects = Resources/States (production line capacity ↔ qubit counts)
- Morphisms = Processes/Gates (manufacturing tasks ↔ quantum operations)
- Composition = Task sequencing (serial: ∘) and parallelization (parallel: ⊗)
- Rewrite rules = Process optimization (semantics-preserving transformations)
The Functorial Pattern
Both domains implement the same hierarchical decomposition functor:
High-level specification ────F───→ Low-level operations
↓ ↓
Sub-tasks Primitive actions
↓ ↓
Validation Semantic preservation
Where F preserves compositional structure (F(g ∘ f) = F(g) ∘ F(f)) ensuring that:
- Factory plans decompose correctly into production line tasks
- Quantum circuits decompose correctly into spider diagrams
- Optimizations at any level preserve overall semantics
Cost Optimization Parallel
Manufacturing (Breiner et al.):
- High-level planning (strategic decisions) → expensive computational resources
- Low-level execution (machine operations) → deterministic, fast
- Strategy: Formalize relationships to enable automated reasoning at lower levels
Quantum Circuits (This MCP):
- High-level synthesis (natural language explanations) → expensive LLM tokens
- Low-level operations (gate taxonomy, parsing) → deterministic, 0 tokens
- Strategy: Encode domain expertise categorically, reserve LLM for interpretation
Both achieve cost savings through deterministic categorical layers rather than recalculating everything from scratch at each level.
Generalization Potential
This pattern applies to any compositional domain:
- Manufacturing: Tasks compose into workflows
- Quantum computing: Gates compose into circuits
- Creative AI: Aesthetic parameters compose into prompts
- Software engineering: Functions compose into programs
- Biological systems: Reactions compose into pathways
The common requirement: compositional semantics that can be formalized as a symmetric monoidal category.
References
-
Bob Coecke & Aleks Kissinger. Picturing Quantum Processes: A First Course in Quantum Theory and Diagrammatic Reasoning. Cambridge University Press, 2017.
- Foundational textbook on ZX-calculus and categorical quantum mechanics
-
Bob Coecke & Ross Duncan. "Interacting Quantum Observables: Categorical Algebra and Diagrammatics." New Journal of Physics 13.4 (2011): 043016.
- Original ZX-calculus formulation with completeness proof
-
Spencer Breiner, Albert Jones & Eswaran Subrahmanian. "Categorical Models for Process Planning." Computer Industry 112 (2019).
- Process hierarchy decomposition using symmetric monoidal categories
- Theoretical validation for hierarchical categorical architectures
-
PyZX Library: https://github.com/zxcalc/pyzx
- Python implementation of ZX-calculus (our taxonomy is compatible)
-
ZX-Calculus Resource: https://zxcalculus.com/
- Community portal with interactive tutorials
Categorical Composition Theory
This server demonstrates functorial decomposition of quantum circuits:
Circuit (high-level) ──────────────────> ZX-diagram (semantic)
│ │
│ Functor F │ Functor G
↓ ↓
Gate sequence (syntax) ─────────────────> Spider graph (rewrite rules)
Where:
- F: Circuit parsing functor (syntax → structure)
- G: Optimization functor (semantics → strategies)
- Composition: G ∘ F preserves quantum semantics while enabling classical simplification
This pattern generalizes to any domain with compositional structure - see Lushy's framework of 50+ categorical MCP servers across diverse aesthetic domains.
Use Cases
Quantum Computing Education
- Teach ZX-calculus interactively with natural language explanations
- Visualize how quantum gates compose categorically
- Step-through circuit simplifications with mathematical justification
Research & Development
- Rapid prototyping of quantum algorithms
- Circuit optimization with T-count minimization
- Measurement-based quantum computation experiments
Fault-Tolerant Compilation
- Analyze resource requirements (T-count, Clifford depth)
- Optimize circuits for error correction codes
- Compare optimization strategies quantitatively
Integration with AI Workflows
- Compositional semantics for multi-domain AI systems
- Deterministic computation layers for cost optimization
- Educational synthesis for domain knowledge transfer
Relationship to Lushy.app Framework
This MCP server is part of the Lushy categorical composition ecosystem, which applies the same 4-layer architecture across 50+ domains:
Common pattern:
- Layer 1: Deterministic domain taxonomy (0 tokens)
- Layer 2: Compositional operations (0 tokens)
- Layer 3: Strategy selection (0 tokens)
- Layer 4: Claude synthesis (~100-200 tokens)
Other Lushy domains:
- Heraldic blazonry (visual vocabulary + tincture rules)
- Jazz improvisation (chord progressions + modal theory)
- Microscopy aesthetics (fluorescence channels + scale context)
- Nuclear explosion phases (fireball dynamics + atmospheric effects)
Cross-domain composition:
- Compatibility matrices determine which domains compose safely
- Graph-theoretic analysis reveals aesthetic clusters
- Frobenius ordering minimizes synthesis cost
Contributing
We welcome contributions! Areas of interest:
- Gate coverage expansion: Add parametric gates (Rx, Ry, Rz), controlled operations
- Additional rewrite rules: Implement local complementation, phase teleportation
- Visualization improvements: Interactive SVG with hover states, animation sequences
- Backend integrations: Qiskit runtime, Cirq compatibility, QASM 3.0 support
- Educational content: Tutorial notebooks, worked examples, proof walkthroughs
Development Setup
# Install development dependencies
pip install -e ".[dev]"
# Run tests with coverage
pytest --cov=quantum_zx_calculus tests/
# Format code
black quantum_zx_calculus/
flake8 quantum_zx_calculus/
# Type checking
mypy quantum_zx_calculus/
Citation
If you use this server in academic work, please cite:
@software{quantum_zx_mcp,
author = {Marsters, Dal},
title = {Quantum ZX-Calculus MCP Server: Categorical Circuit Optimization},
year = {2025},
url = {https://github.com/dmarsters/quantum-zx-calculus-mcp},
note = {MCP server implementing ZX-calculus with hierarchical categorical architecture}
}
And the foundational ZX-calculus work:
@book{coecke2017picturing,
title={Picturing Quantum Processes},
author={Coecke, Bob and Kissinger, Aleks},
year={2017},
publisher={Cambridge University Press}
}
License
MIT License - see LICENSE file for details.
Contact
Dal Marsters
Co-founder, Lushy
dal@lushy.app
https://www.linkedin.com/in/dalmarsters/
For questions about:
- Categorical theory: See theoretical foundation section
- Implementation details: Open a GitHub issue
- Academic collaboration: Email directly
- Commercial applications: Via Lushy website
Acknowledgements
- Bob Coecke & Aleks Kissinger: ZX-calculus theoretical foundation
- PyZX team: Reference implementation and community resources
- Spencer Breiner et al.: Categorical process planning framework (NIST)
- Applied Category Theory community: Compositional semantics research