Quantum Hardware MCP Server

A production MCP server that gives AI assistants programmatic access to live quantum hardware — IBM Quantum and IonQ. 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

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.

System architecture

graph TD
    User["User / AI Assistant"]

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

    subgraph Execution Plane
        MCP["MCP Server\nserver.py\n26 tools"]
        IBMAPI["IBM Quantum API\nQiskit Runtime"]
        IonQAPI["IonQ REST API"]
    end

    subgraph Observability Plane
        Snapshot["snapshot.py\nRuns every 6h"]
        DB["devices.db\nSQLite — local history"]
        CSV["data/snapshots.csv\nPublic — GitHub Actions CI"]
        Report["report.py\nDaily fleet report"]
        Alerts["Calibration drift alerts\n>20% spike detection"]
    end

    User --> Dispatcher
    Dispatcher --> IBMAgent
    Dispatcher --> IonQAgent
    IBMAgent --> MCP
    IonQAgent --> MCP
    MCP --> IBMAPI
    MCP --> IonQAPI
    Snapshot --> DB
    Snapshot --> CSV
    Snapshot --> Alerts
    DB --> 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 6 hours, snapshot.py records calibration state across all providers. Drift alerts fire when any metric spikes >20%. repro_score runs KL-divergence across N identical runs to quantify hardware reliability.

Planes

Control plane — routing and coordination

Execution plane — quantum hardware interface

26 tools across IBM Quantum (22) and IonQ (4). 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 6 hours via GitHub Actions and a local LaunchAgent:

• Collects IBM + IonQ + AWS Braket calibration data — CX error, readout error, T1/T2, queue depth
• Locally: writes to devices.db (SQLite) — feeds device_history, device_on_date, drift alerts
• CI: appends to data/snapshots.csv — public, committed to the repo, permanent 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_kingston

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.

Amplification degrades predictably with circuit depth — itself a useful noise characterization. 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 26 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 26 IBM + IonQ tools
├── snapshot.py                    # Multi-provider calibration snapshot agent
├── 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 for Singmaster's Conjecture
│   ├── singmasters_3003.py        # Phase 2 — 3003 in Pascal's Triangle
│   └── 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)
└── .github/workflows/
    └── snapshot.yml               # GitHub Actions: snapshot every 6h

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 26 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 when you explicitly submit a job.

Roadmap

• IBM Quantum tools — device intelligence, job lifecycle, pre-flight, routing
• IonQ support — devices, submit, status, results
• Multi-agent control plane — dispatcher + IBM/IonQ specialist subagents
• Calibration drift alerts — auto-detects >20% error spikes
• 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
• Singmaster's Conjecture — Grover's search — 4.11x amplification on real hardware
• VQE for H2 — chemical accuracy (0.0 mHartree) on simulator
• Multi-provider snapshot pipeline — IBM + IonQ + AWS Braket, every 6h
• 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
• 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 (inspired by quantum-assistant which fine-tunes VLMs on quantum visuals) — ask Jack on Monday

License

MIT — see LICENSE.