Which integrations are available for this server?

Generates markdown visualizations of ZX-diagrams for documentation and educational content. Converts Qiskit quantum circuits into ZX-diagram format using categorical quantum mechanics, with support for gate taxonomy mapping and circuit simplification. Generates SVG visualizations of ZX-diagrams for educational purposes and quantum circuit representation.

How do I use Quantum ZX-Calculus MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Quantum ZX-Calculus MCP Server convert this QASM circuit to a ZX-diagram and simplify it" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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