Quantum Hardware MCP Server

A quantum hardware orchestration and intelligence layer that gives AI agents the ability to select, validate, execute, and analyze quantum experiments across multiple providers. Natural language in. Real quantum results out. No dashboards. No manual API calls.

Built in collaboration with Jack Woehr — IBM Quantum veteran, Qiskit contributor.

Why this exists

Quantum researchers lose hours to operational overhead:

• Manually checking which device has the lowest error rate today

• Submitting the same circuit to IBM, then separately to IonQ, then comparing by hand

• Losing reproducibility context between runs — "what was the CX error when I ran Figure 3?"

• No pre-flight — wasting queue time on circuits that fail at transpile

• No cross-provider queue visibility — IBM backlogged for 3 days, IonQ open, no way to know without checking each dashboard manually

• Discovering routing failures only after wasting QPU credits — a degree-4 qubit on heavy-hex silently causes 4× gate inflation

This server eliminates that overhead. Your AI assistant handles device selection, circuit validation, routing overhead prediction, job submission, result retrieval, and amplification analysis through a single interface.

Related MCP server: mcp-qiskit

What we discovered running real experiments

We have been using this server to run real quantum experiments on IBM ibm_marrakesh — not just as a demo, but as active research infrastructure. The results changed how we built the server.

The routing failure discovery (Phase 4): We built a 7-qubit Grover circuit to search Pascal's Triangle for rows where 3003 appears. The circuit had 263 logical gates. After transpilation: 1,037 hardware gates. The signal collapsed.

The root cause was not the transpiler. It was graph embedding: one ancilla qubit needed 4 direct connections in the circuit interaction graph. IBM heavy-hex topology allows max 3 connections per qubit. The transpiler had no choice but to inject ~300 SWAP gates (3 CX each) to route around the constraint.

This is now baked into the server as check_routing_overhead — it detects degree-4 violations before you submit.

The LNAA approach (Phase 5): After discovering that Grover's oracle structure creates an unfixable degree-4 node on heavy-hex, we scrapped Grover entirely. Instead of a Boolean oracle, we built an Ising Hamiltonian — the same encoding family behind QAOA and quantum annealing — where target rows (14, 15, 78, found classically via the Lucas-theorem sieve beforehand) are the ground states. IBM's RZZ and RX gates implement this natively — no routing, no SWAP, no ancilla.

Result: 27.78× amplitude amplification, preparing and confirming those already-known target states, with 135 hardware gates on ibm_marrakesh.

Previous best: 4.17× with 103 gates (Phase 3, Grover).

Important honesty note: the sieve (classical, microseconds) finds which rows collide. The quantum circuit doesn't discover that fact — it demonstrates that a hardware-native encoding can prepare and amplify those known target states without routing overhead, at scale, in one job. That's a real result about circuit design and hardware efficiency, not a mathematical discovery. We call the technique LNAA (Lattice-Native Amplitude Amplification) as a name for this specific application of Ising-Hamiltonian encoding to Pascal's Triangle collision search — the underlying math (Ising embeddings, native-gate execution) is well-established, not new. The insight worth keeping — encode targets as ground states, not Boolean conditions, so the circuit matches the hardware's native connectivity — is now the encode_search_problem tool.

Fleet coverage

19 backends across three providers:

All 19 are polled every 2 hours. The dataset grows continuously — ML routing recommendations are planned once 60+ days of data accumulate.

System architecture

graph TD
    User["User / AI Assistant"]

    subgraph Control Plane
        Dispatcher["Dispatcher\nagent-server.js\nRoutes IBM vs IonQ vs Braket"]
        IBMAgent["IBM Subagent\nibm-subagent.js"]
        IonQAgent["IonQ Subagent\nionq-subagent.js"]
    end

    subgraph Execution Plane
        MCP["MCP Server\nserver.py + tools_chemistry.py\n50 tools"]
        IBMAPI["IBM Quantum API\nQiskit Runtime"]
        IonQAPI["IonQ REST API"]
        BraketAPI["AWS Braket API"]
    end

    subgraph Observability Plane
        Snapshot["snapshot.py\nRuns every 2h"]
        DB["devices.db\nSQLite — local history"]
        CSV["data/snapshots.csv\nPublic — GitHub Actions CI"]
        Jobs["job_submissions\nAgentic workload log"]
        Report["report.py\nDaily fleet report"]
        Alerts["Calibration drift alerts\nCX / readout / T1 / T2"]
    end

    User --> Dispatcher
    Dispatcher --> IBMAgent
    Dispatcher --> IonQAgent
    IBMAgent --> MCP
    IonQAgent --> MCP
    MCP --> IBMAPI
    MCP --> IonQAPI
    MCP --> BraketAPI
    Snapshot --> DB
    Snapshot --> CSV
    Snapshot --> Alerts
    MCP --> Jobs
    DB --> MCP
    Jobs --> MCP
    Report --> DB

How it works

Step 1 — Request classification The dispatcher reads your message and classifies it: IBM job, IonQ job, or cross-provider comparison. Each subagent sees only the tools for its provider — no accidental cross-wiring.

Step 2 — Pre-flight validation Before touching the queue, debug_circuit catches missing measurements, decoherence bound violations, and qubit count mismatches. circuit_report does a full dry-run transpile — gate counts, qubit mapping, per-pair CX error, estimated fidelity — all without submitting. check_routing_overhead detects degree-4 qubit violations that would cause SWAP flooding.

Step 3 — Credit-aware routing estimate_runtime computes QPU minutes before submission. route_job ranks backends by cost × error rate and picks the cheapest option that meets your fidelity requirement.

Step 4 — Execution submit_job compiles to the backend's native gate set (OpenQASM 2.0 or 3.0), submits, and returns a job_id. job_status and job_results close the loop.

Step 5 — Analysis get_amplification computes the amplification factor directly from a job ID and your marked bitstrings — no manual result parsing.

Step 6 — Observability Every 2 hours, snapshot.py records calibration state across all 19 backends. Drift alerts fire when CX error, readout error, T1, or T2 spikes >20%. repro_score runs KL-divergence across N identical runs to quantify hardware reliability. Every job submission is logged for longitudinal workload analysis.

Tools (50 total)

Device intelligence

Quantum chemistry planning (qforge)

The tools above answer "what hardware exists, and is my circuit valid?". These answer the question a chemist starts with: "I have this molecule — can I run it, by what method, and what will it cost?" All values are computed from geometry by the qforge library in this repo; nothing is looked up.

The last three complete the loop: molecule → circuits → hardware → energy.

run_forged_energy(atoms="H 0 0 0; H 0 0 0.74", n_electrons=2,
                  device_name="ibm_fez", schmidt_rank=2)
→ 8 circuits on 2 qubits (H2 would otherwise need 4), job IDs returned
collect_forged_energy(..., job_ids="...")
→ measured energy vs exact −1.137284 Ha

Circuits are replayed on a local simulator before anything is submitted — a wrong measurement basis or sign produces a quietly wrong energy rather than an obvious failure, so run_forged_energy refuses to submit if the self-check fails. Job counts are capped by default; raise max_circuits deliberately.

Example — "can I run H4 on $3,000 of credits?":

plan_quantum_chemistry_run(
    atoms="H 0 0 0; H 1 0 0; H 2 0 0; H 3 0 0",
    n_electrons=4,
    budget_usd=3000,
)
→ Schmidt rank 4: 80 circuits, ~$2,063, floor 1.53 kcal/mol

Requires qiskit-nature (in requirements.txt). The tools import lazily, so the rest of the server still runs if it is missing.

Job lifecycle

Pre-flight and cost control

Circuit intelligence (derived from real experiments)

Algorithms and chemistry

Discovery tools (Singmaster pipeline)

Observability

IonQ

Real experiments: Singmaster's Conjecture on IBM hardware

These tools were validated end-to-end using Singmaster's Conjecture (does any integer appear 9+ times in Pascal's Triangle?) as a real hardware case study — not a demo. encode_4way_collision achieved 178.8× amplitude amplification on real IBM hardware (ibm_fez, job d97fk8t2su3c739i26fg), simultaneously confirming 4 classically-known target rows in one job — up from 4.17× in the project's earlier Grover-based approach. All job IDs are real and reproducible.

Key insight: IBM heavy-hex is an Ising lattice. RZZ + RX gates are native — zero routing overhead. Encoding targets as ground states of a Hamiltonian outperforms Boolean oracle + diffusion when hardware topology constrains qubit degree ≤ 3.

Full experiment history, result tables, and IonQ cross-vendor work live in a private research repo — reach out if you'd like access.

Observability plane — calibration history

snapshot.py runs every 2 hours via GitHub Actions:

Job submissions table — every call to submit_job, run_grover, or run_vqe writes a row:

job_id · provider · backend · tool · circuit_qubits · circuit_depth_raw
circuit_depth_transpiled · shots · agent_loop_iteration
was_preflight_checked · was_ai_corrected · day_of_week · hour_utc

Test suite

pytest tests/ --ignore=tests/test_all_tools.py

92 passing — device tools, IonQ endianness/angle-unit canaries, qforge chemistry (library + MCP integration), dispatcher unit tests. No QPU credits spent; IonQ checks run against the free simulator, including realistic per-device noise-model previews.

test_all_tools.py is a separate live-hardware smoke test — needs real IBM/IonQ credentials configured, run it directly rather than through pytest.

test_agent_routing.py needs the Docker agent service running and reachable at localhost:3021 — currently failing in this environment (known issue, not yet root-caused; unrelated to the MCP server tools themselves).

Project structure

quantum-hardware-mcp/
├── server.py                      # MCP server — IBM + IonQ hardware tools
├── tools_chemistry.py             # qforge chemistry tools (7), registered on the same server
├── mcp_app.py                     # Shared FastMCP instance, so both sides register on one server
├── qforge/                        # Quantum chemistry library — integrals, forging, mitigation
├── snapshot.py                    # Multi-provider calibration snapshot (every 2h)
├── report.py                      # Daily fleet report
├── requirements.txt
├── docker-compose.yml
├── Dockerfile
├── .env.example
├── agent/
│   ├── agent-server.js            # Dispatcher — control plane router
│   ├── chat.js                    # Terminal interface
│   └── subagents/
│       ├── base-subagent.js       # Shared ReAct loop
│       ├── ibm-subagent.js        # IBM specialist
│       └── ionq-subagent.js       # IonQ specialist
├── experiments/
│   └── vqe_h2.py                  # VQE for H2 molecule ground state
│                                   # (Singmaster's Conjecture phase history moved to the
│                                   #  private singmasters-conjecture repo — full journey,
│                                   #  178.8× hardware result, and job IDs live there)
├── tests/
│   ├── test_all_tools.py          # Smoke test suite (needs live IBM credentials)
│   ├── test_server_tools.py       # IBM + IonQ device/job tool tests
│   ├── test_ionq_canaries.py      # Endianness + angle-unit regression tests (IonQ)
│   ├── test_qforge.py             # qforge library unit tests
│   ├── test_qforge_tools.py       # Chemistry MCP tool tests
│   ├── test_agent_routing.py      # Dispatcher routing tests
│   └── test_dispatcher.py         # Dispatcher unit tests
├── data/
│   └── snapshots.csv              # Public calibration history (updated by CI every 2h)
└── .github/workflows/
    └── snapshot.yml               # GitHub Actions: snapshot every 2h

Quick start

Prerequisites: Python 3.10+, Node.js 18+, IBM Quantum account (free), LLM API key.

git clone https://github.com/Lokesh-2025/quantum-hardware-mcp.git
cd quantum-hardware-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cd agent && npm install && cd ..
cp .env.example .env        # add IBM token + LLM key
docker compose up --build   # starts MCP server + agent
node agent/chat.js          # open terminal chat

Connect to Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "quantum-hardware": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/quantum-hardware-mcp/server.py"]
    }
  }
}

Restart Claude Desktop. All 50 tools appear under the hammer icon.

LLM provider support

Roadmap

Completed

• IBM Quantum tools — device intelligence, job lifecycle, pre-flight, routing

• IonQ support — devices, submit, status, results

• AWS Braket integration — 10 backends in snapshot pipeline

• Multi-agent control plane — dispatcher + IBM/IonQ specialist subagents

• Calibration drift alerts — CX error, readout error, T1, T2

• Reproducibility scoring — KL-divergence across N runs

• Credit-aware routing — QPU cost estimation before submit

• Singmaster Phase 1 — Grover 4.11× (depth 611)

• Singmaster Phase 2 — coherence limit bracketed at depth 16,271

• Singmaster Phase 3 v3 — 4.17× at 103 gates (99.4% reduction from Phase 2)

• Singmaster Phase 4 v1 — 7 qubits, row 78 found, 3.04×

• Singmaster Phase 4 v2 — routing failure diagnosed as graph embedding problem

• Singmaster Phase 5 LNAA — 27.78× amplification, 135 gates

• check_routing_overhead — degree>3 detection before SWAP flood

• encode_search_problem — Boolean conditions → Ising Hamiltonian coefficients

• estimate_hardware_gates — predicts transpiled gate count + noise floor warning

• get_amplification — amplification factor from job ID + marked bitstrings

• best_qubits connectivity check — warns when top qubits aren't physically linked

• Temporal indexing — day_of_week + hour_utc on all snapshots and jobs

• Job submissions table — transpilation expansion ratio tracking

• Listed on Glama, mcp.so, PulseMCP

• encode_collision_problem — auto-finds C(n1,k1)=C(n2,k2) pairs, encodes as Ising (122.92× sim)

• run_parallel_collision_search — N simultaneous LNAA rails in one hardware job (~300× ibm_kingston)

• sieve_singmaster_space — Lucas theorem sieve, validated 3003 at 8 positions, searched n=50k

• encode_4way_collision — multi-column parallel LNAA, 178.8× on ibm_fez — first hardware-confirmed 4-way Pascal collision

• Singmaster Step 3 — ~300× amplification, 30 qubits, ibm_kingston

• Singmaster Step 4 — 178.8× amplification, 24 qubits, ibm_fez (hardware record)

Next

• Web interface — visual frontend for device comparison, job submission, circuit playground, live results (in progress: quantum-hardware-web)

• inject_topological_walk — bypass transpiler using calibration DB, map directly to high-coherence qubits

• discover_energy_landscape — LNAA parameter sweep → full energy landscape visualization

• algorithm_selector — decides Grover vs LNAA based on circuit + hardware analysis

• VQE on real IBM hardware — H2 hardware result

• Quantum Rush Hour detection — weekly queue seasonality

• Smart routing brain — cross-provider ML recommendations

• Publication package generator — job ID → figures + BibTeX + methods section

License

MIT — see LICENSE.