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.

Product	Identifier	Version
VS Code Extension	markusvankempen.quantum-openqasm-assistant	1.9.2
NPM MCP Server	@markusvankempen/quantum-openqasm-mcp	1.9.2
MCP Registry	io.github.markusvankempen/quantum-openqasm-mcp	1.9.2
Public repo	quantum-openqasm-assistant	tag v1.9.2 — docs & deployment guides only

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<br/>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 · Project structure → docs/PROJECT-STRUCTURE.md · OpenQASM Primer → docs/OPENQASM-PRIMER.md · Tips & Tricks → docs/TIPS-AND-TRICKS.md · Architecture → docs/ARCHITECTURE.md · Local MCP setup → docs/ide/LOCAL-MCP-SETUP.md · Qiskit Developer Pack → docs/ide/QISKIT-DEVELOPER-PACK.md · Deployment → docs/deployments/DEPLOYMENT-SCENARIOS.md · Extension → extension/README.md · Contributing → 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

Feature	Description
Quantum Lab	Interactive OpenQASM panel with example circuits and histogram results
Qiskit Lab	Dedicated Qiskit Python panel — 12 templates, Aer sim, export to OpenQASM
AI Transpilation	qiskit-ibm-transpiler integration for hardware-native circuit optimization
OpenQASM 2.0	IBM hardware ISA format (rz, sx, cz native gates)
MCP tools	list_backends, submit_qasm_job, get_job_status, get_job_results, and more
Multi-IDE MCP	One-click setup for Cursor, VS Code, Bob, Antigravity & Claude Desktop
Qiskit Developer Pack	Bundle Qiskit MCP servers + quantum-openqasm-mcp from Diagnostics
Local / remote	stdio MCP locally or SSE via IBM Code Engine
Diagnostics	Test IAM auth, list backends, save credentials from the UI

---

MCP tools

Tool	Description
list_backends	Available IBM Quantum backends, status, queue
get_backend	Details for a specific backend
submit_qasm_job	Submit OpenQASM 2.0 circuit
get_job_status	Poll job state
get_job_results	Measurement counts / histogram data
cancel_job	Cancel a running job

---

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 for the complete file map.

---

Documentation

Guide	Description
Documentation hub	Index of all published guides
Architecture	System design, MCP, IBM API flow
OpenQASM Primer	Learn OpenQASM 2.0 in plain English
Qiskit integration	Qiskit → export QASM → IBM hardware via MCP / Lab
Tips & Tricks	Backend selection, MCP workflows
Project structure	Complete repo layout
Extension README	VS Code extension features, commands
Local MCP setup	Cursor, VS Code, Bob, Antigravity
Deployment hub	5 client modes + infra (CE, Docker, WxO, CI)
Deployment scenarios	Local, Code Engine, Docker, hybrid

---

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-DEVELOPER-PACK.md

• Example script: examples/qiskit-bell-export.py

---

Security

• API keys live in VS Code settings or ~/.quantum-openqasm-mcp/.env — never in git
• .env, Internal/, and IDE mcp.json files are gitignored
• Report issues via GitHub Issues

---

Contributing

Contributions welcome! See CONTRIBUTING.md for the two-repo model, mise tasks, and PR process.

Please read our CODE_OF_CONDUCT.md.

---

License

Apache License 2.0

---

Topics & keywords

quantum-computing · quantum-computer · openqasm · openqasm-2 · qasm · ibm-quantum · ibm-cloud · qiskit · quantum-circuit · quantum-hardware · quantum-lab · quantum-programming · quantum-physics · qubit · bell-state · quantum-job · quantum-backend · mcp · model-context-protocol · mcp-server · vscode-extension · cursor · ibm-bob · antigravity · copilot · ai-assistant · typescript · nodejs · histogram · sampler-v2 · code-engine · cloud-quantum

---

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.