Quantum OpenQASM MCP

Quantum OpenQASM Assistant

Quantum OpenQASM Assistant is a VS Code extension and Model Context Protocol (MCP) server for IBM Quantum — submit OpenQASM 2.0 circuits to real quantum hardware and simulators from Cursor, VS Code, IBM Bob, and Google Antigravity. Includes Quantum Lab (interactive circuit editor), live job polling, measurement histograms, Bell state / GHZ examples, SamplerV2 REST integration, and one-click MCP setup for AI coding assistants.

Search terms: quantum computing · openqasm · qasm · ibm quantum · qiskit · quantum circuit · quantum hardware · mcp server · model context protocol · cursor mcp · vscode quantum · ai quantum assistant · quantum programming · qubit · bell state

Author: Markus van Kempen Email: markus.van.kempen@gmail.com · mvk@ca.ibm.com Website: markusvankempen.github.io *No bug too small, no syntax too weird.*

---

Overview

Quantum OpenQASM Assistant connects AI agents and developers to IBM Quantum through a pure TypeScript MCP server and VS Code extension. Submit OpenQASM 2.0 ISA circuits, poll job status, and view measurement histograms — locally via stdio or remotely via SSE on IBM Code Engine.

Source code is maintained in the private dev repo quantum-openqasm-assistant-dev. Install the product via VS Code Marketplace or npm MCP — not by cloning this repo for extension source.

graph TB

subgraph clients [MCP Clients] Cursor[Cursor / VS Code] Bob[IBM Bob] AG[Antigravity] Lab[Quantum Lab Extension] end

subgraph mcp [MCP Server] Local["server.ts stdio"] Remote["server-sse.ts SSE"] end

IBM["IBM Quantum REST API SamplerV2 · OpenQASM 2.0"]

Cursor -->|stdio| Local Bob -->|stdio| Local AG -->|stdio| Local Lab -->|stdio or SSE| Local Lab -->|SSE| Remote Local --> IBM Remote --> IBM

sequenceDiagram

participant User participant Ext as VS Code Extension participant MCP as MCP Server participant IBM as IBM Quantum API

User->>Ext: Submit .qasm circuit Ext->>MCP: submit_qasm_job MCP->>IBM: POST /jobs (SamplerV2) IBM-->>MCP: job id MCP-->>Ext: job id loop Poll every 15s Ext->>MCP: get_job_status MCP->>IBM: GET /jobs/{id} IBM-->>Ext: Queued → Running → Completed end Ext->>MCP: get_job_results MCP->>IBM: GET /jobs/{id}/results IBM-->>Ext: measurement histogram

📖 [Documentation hub → docs/README.md](./docs/README.md) · [Project structure → docs/PROJECT-STRUCTURE.md](./docs/PROJECT-STRUCTURE.md) · [OpenQASM Primer → docs/OPENQASM-PRIMER.md](./docs/OPENQASM-PRIMER.md) · [Tips & Tricks → docs/TIPS-AND-TRICKS.md](./docs/TIPS-AND-TRICKS.md) · [Architecture → docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) · [Local MCP setup → docs/ide/LOCAL-MCP-SETUP.md](./docs/ide/LOCAL-MCP-SETUP.md) · [Qiskit Developer Pack → docs/ide/QISKIT-DEVELOPER-PACK.md](./docs/ide/QISKIT-DEVELOPER-PACK.md) · [Deployment → docs/deployments/DEPLOYMENT-SCENARIOS.md](./docs/deployments/DEPLOYMENT-SCENARIOS.md) · [Extension → extension/README.md](./extension/README.md) · [Contributing → CONTRIBUTING.md](./CONTRIBUTING.md)

Repository policy: This public GitHub repo publishes overview and setup documentation. Extension source code, scripts, and examples live in the private dev repo (use .gitignore.private when setting it up).

---

Features

---

MCP tools

---

Quick start

Prerequisites

• Node.js 18+ (mise recommended — see mise.toml)
• IBM Cloud API key + Quantum Service CRN — cloud.ibm.com/iam/apikeys

Build (private dev repo)

mise run install

mise run build

Configure

cp .env.example .env

IBM_API_KEY, IBM_SERVICE_CRN, IBM_QUANTUM_ENDPOINT, IBM_QUANTUM_BACKEND

Or use Quantum → Settings & Diagnostics in the extension.

Test

mise run test-e2e

or: Press F5 in VS Code → Quantum Lab → Run on Hardware

Install extension

mise run package

code --install-extension extension/quantum-openqasm-assistant-*.vsix

---

Architecture at a glance

quantum-openqasm-assistant/

├── extension/ # VS Code extension + bundled MCP server │ ├── src/extension.ts # Extension entry, MCP client │ ├── src/server.ts # Local stdio MCP server │ ├── src/server-sse.ts # Remote SSE MCP server │ └── out/ # esbuild output ├── packages/ │ └── quantum-openqasm-mcp/ # Standalone npm MCP package ├── scripts/ # MCP launcher, e2e tests, examples ├── docs/ # Published documentation │ └── QISKIT-INTEGRATION.md # Qiskit → OpenQASM → IBM Quantum ├── examples/ # Qiskit export script (public) ├── deployments/ # Client modes + infrastructure │ ├── README.md # Hub: 5 client modes + 6 infra scenarios │ ├── extension-only/ # Mode 1 │ ├── extension-mcp-local/# Mode 2 │ ├── mcp-npm/ # Mode 3 │ ├── extension-remote-mcp/# Mode 4 │ ├── mcp-remote-sse/ # Mode 5 │ ├── code-engine/ # IBM Code Engine │ ├── local-bridge/ # Dev gateway │ ├── docker-sse/ # Self-hosted │ ├── secured-remote/ # Auth tiers │ ├── wxo-orchestrate/ # Orchestrate agents │ └── ci-cd/ # Pipeline smoke tests └── Internal/ # Branding, publishing, status (gitignored)

See [docs/PROJECT-STRUCTURE.md](./docs/PROJECT-STRUCTURE.md) for the complete file map.

---

Documentation

---

Qiskit Integration

Design circuits in Qiskit (or the built-in Qiskit Lab panel), export to OpenQASM 2.0, transpile with AI-powered `qiskit-ibm-transpiler`, and run on IBM Quantum hardware:

from qiskit import QuantumCircuit, qasm2

qc = QuantumCircuit(2, 2) qc.h(0) qc.cx(0, 1) qc.measure([0, 1], [0, 1])

print(qasm2.dumps(qc)) # → submit via MCP or paste into Quantum Lab

OPENQASM 2.0;

include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q[0] -> c[0]; measure q[1] -> c[1];

No Qiskit dependency at runtime — the MCP server speaks OpenQASM + IBM Quantum REST directly.

v1.9.2 Qiskit features:

• Qiskit Lab — 12 templates (Bell, GHZ, Grover, teleportation, VQE ansatz, QAOA, …), local Aer sim, one-click export
• AI transpilation — qiskit-ibm-transpiler MCP integration for hardware-native optimization
• `quantum-assistant` MCP — streamlined MCP key for AI IDE setup

• Full guide: docs/QISKIT-INTEGRATION.md
• Qiskit Developer Pack (Qiskit MCP + AI transpiler + OpenQASM): [docs/ide/QISKIT-