Quantum Hardware MCP Server

A production MCP server that gives AI assistants programmatic access to live quantum hardware across IBM Quantum, IonQ, and AWS Braket. Natural language in. Real quantum results out. No dashboards. No manual API calls.

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

Listed on Glama, mcp.so, and PulseMCP.

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

This server eliminates that overhead. Your AI assistant handles device selection, circuit validation, job submission, result retrieval, and cross-provider comparison through a single interface.

Related MCP server: qiskit-sim-mcp

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\n27 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.

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 — 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.

Planes

Control plane — routing and coordination

Execution plane — quantum hardware interface

27 tools across IBM Quantum (22), IonQ (4), and analytics (1). All live in server.py.

IBM Quantum — device intelligence

IBM Quantum — job lifecycle

IBM Quantum — pre-flight and cost control

IBM Quantum — algorithms and chemistry

IBM Quantum — observability

IonQ

Observability plane — calibration history

snapshot.py runs every 2 hours via GitHub Actions (was 6h — upgraded for higher-resolution Rush Hour detection):

Per-snapshot fields collected:

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

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

This is the foundation for a first-of-its-kind agentic quantum workload study — once the dataset matures we can answer: which backends see the most AI-driven traffic, what is the typical transpilation expansion ratio by provider, how does shot count correlate with circuit depth.

Storage:

• devices.db (SQLite, local) — feeds device_history, device_on_date, drift alerts, job_analytics

• data/snapshots.csv (public, committed by CI) — permanent append-only calibration record

report.py generates a daily fleet summary at 8am — error trends, device rankings, alert history.

Real experiments on quantum hardware

Pascal's Triangle encoding — IBM ibm_kingston

Binary-encode Pascal's Triangle values as quantum states, measure preparation fidelity on real superconducting hardware.

Singmaster's Conjecture — Grover's search — IBM ibm_marrakesh

Singmaster's Conjecture asks whether any integer appears 9+ times in Pascal's Triangle. We use Grover's search to amplify rows containing a target value above the noise floor.

Phase 2 is not a failure — it brackets the coherence limit of ibm_marrakesh between 611 and 16,271 transpiled gates. The 161× transpilation expansion ratio (101 raw gates → 16,271 after routing and basis translation) is itself a hardware characterization result: IBM heavy-hex topology forces gate decompositions that blow up shallow circuits. This number belongs in the paper.

Full code and raw results: singmasters-conjecture (collaboration with Jack Woehr).

VQE — H2 molecule ground state energy

Variational Quantum Eigensolver on a 2-qubit hardware-efficient ansatz (RY + CNOT). COBYLA optimizer.

Chemical accuracy threshold: < 1.6 mHa. Simulator achieves exact convergence. Real hardware run pending — IonQ trapped ions expected to outperform IBM superconducting due to lower gate error.

This is a stepping stone toward receptor-ligand binding energy simulations for drug discovery research.

Test suite

python tests/test_all_tools.py

28 checks across all 27 tools. Read-only tools hit the real IBM and IonQ APIs. Write tools are tested against validation paths only — zero QPU credits spent.

Total: 28 checks | ✅ 28 passed | ❌ 0 failed | ⏭️  0 skipped
All tools operational!

Project structure

quantum-hardware-mcp/
├── server.py                      # MCP server — all 27 IBM + IonQ + analytics tools
├── snapshot.py                    # Multi-provider calibration snapshot agent (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/
│   ├── singmasters_grover.py      # Grover's search — Phase 1 (target: 6)
│   ├── singmasters_3003.py        # Grover's search — Phase 2 (target: 3003, coherence limit)
│   └── vqe_h2.py                  # VQE for H2 molecule ground state
├── tests/
│   └── test_all_tools.py          # 28-check smoke test suite
├── 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 27 tools appear under the hammer icon.

LLM provider support

For sensitive research (pharmaceutical, unpublished academic work): run Ollama locally. The LLM never leaves your machine. The MCP server only contacts IBM/IonQ/Braket when you explicitly submit a job.

Roadmap

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

• IonQ support — devices, submit, status, results

• AWS Braket integration — 10 backends added to snapshot pipeline

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

• Calibration drift alerts — CX error, readout error, T1, T2 (LAG window detection)

• Reproducibility scoring — KL-divergence across N runs

• Credit-aware routing — QPU cost estimation before submit

• Pascal's Triangle on real IBM hardware — 94.2% fidelity at C(6,3)

• Singmaster's Conjecture Phase 1 — Grover's search — 4.11× amplification (depth 611)

• Singmaster's Conjecture Phase 2 — coherence limit bracketed at depth 16,271 on ibm_marrakesh

• VQE for H2 — chemical accuracy (0.0 mHartree) on simulator

• Multi-provider snapshot pipeline — IBM + IonQ + AWS Braket, every 2h (upgraded from 6h)

• Extended calibration fields — 11 fields per snapshot including median T1/T2, qubit yield, connectivity density

• Temporal indexing — day_of_week + hour_utc on every snapshot and job submission

• Job submissions table — agentic workload tracking with transpilation expansion ratios

• job_analytics tool — aggregate workload stats across all submitted jobs

• Full smoke test suite — 28/28 passing, zero QPU credits spent

• Listed on Glama, mcp.so, PulseMCP

• IonQ real hardware experiments (QPU access pending)

• VQE on real IBM hardware — H2 hardware result

• Circuit fingerprinting — cache results, skip resubmitting identical circuits

• Quantum Rush Hour detection — weekly queue seasonality via STL decomposition (needs 60+ days of data)

• Smart routing brain — cross-provider ML recommendations (needs 60+ days of data)

• Autonomous daily report agent

• Circuit image understanding — accept a circuit diagram image as input, interpret and submit

License

MIT — see LICENSE.