@markusvankempen/quantum-openqasm-mcp

@markusvankempen/quantum-openqasm-mcp

Model Context Protocol (MCP) server for IBM Quantum and OpenQASM 2.0. Connect your AI assistant to real quantum hardware — list backends, submit circuits, poll jobs, and read measurement histograms. v1.7.4 · pairs with the Qiskit Developer Pack.

Package: @markusvankempen/quantum-openqasm-mcp · CLI: quantum-openqasm-mcp · Transport: stdio · Node: 18+

Also available: Quantum OpenQASM Assistant — VS Code / Cursor extension with Quantum Lab UI, histogram charts, and one-click MCP setup.

Why use this?

Use case	What you get
AI-assisted quantum experiments	Your LLM can call MCP tools to run circuits on IBM hardware
Cursor / VS Code / Claude Desktop	Drop-in mcp.json config with npx — no Docker required
CI and scripts	Import startQuantumMcpServer() or shell out to the CLI
Pair with the VS Code extension	Same tools the extension spawns locally via out/server.js

How it fits together

  ┌─────────────────┐     stdio      ┌──────────────────────────┐
  │  AI IDE / Agent │ ◄────────────► │  quantum-openqasm-mcp    │
  │  Cursor, VS Code│                │  (this npm package)      │
  │  Claude Desktop │                └────────────┬─────────────┘
  └─────────────────┘                             │
                                                  │ HTTPS + IBM IAM
                                                  ▼
                                    ┌──────────────────────────┐
                                    │  IBM Quantum Platform    │
                                    │  backends · jobs · counts │
                                    └──────────────────────────┘

Install

# Global CLI
npm install -g @markusvankempen/quantum-openqasm-mcp

# Or run once without installing (recommended for MCP clients)
npx @markusvankempen/quantum-openqasm-mcp

Requires Node.js 18 or newer.

Interactive setup

npx @markusvankempen/quantum-openqasm-mcp --setup

Wizard options:

• (a) Write VS Code mcp.json with ${input:...} prompts (recommended — secure)
• (b) Write mcp.json with env vars + .env file
• (c) .env only (for Cursor / npx)

Quick credential check

npx @markusvankempen/quantum-openqasm-mcp --check

Masks values, tests IBM IAM, exits 0 when ready.

The server fails fast at startup if IBM_API_KEY or IBM_SERVICE_CRN are missing (stderr shows setup guidance).

Credentials

Set environment variables or create a .env file in the working directory or at ~/.quantum-openqasm-mcp/.env:

IBM_API_KEY=your_ibm_cloud_api_key
IBM_SERVICE_CRN=crn:v1:bluemix:public:quantum-computing:us-east:a/...
IBM_QUANTUM_ENDPOINT=https://us-east.quantum-computing.cloud.ibm.com
IBM_QUANTUM_BACKEND=ibm_fez

Variable	Where to get it
IBM_API_KEY	IBM Cloud IAM API keys
IBM_SERVICE_CRN	Your IBM Quantum instance page
IBM_QUANTUM_ENDPOINT	Region endpoint (default: us-east)
IBM_QUANTUM_BACKEND	e.g. ibm_fez, ibm_marrakesh, ibm_kingston

MCP client setup

Cursor / Claude Desktop (mcp.json)

{
  "mcpServers": {
    "quantum-openqasm-mcp": {
      "command": "npx",
      "args": ["-y", "@markusvankempen/quantum-openqasm-mcp"],
      "env": {
        "IBM_API_KEY": "your_key",
        "IBM_SERVICE_CRN": "your_crn"
      }
    }
  }
}

With a global install:

{
  "mcpServers": {
    "quantum-openqasm-mcp": {
      "command": "quantum-openqasm-mcp",
      "args": []
    }
  }
}

VS Code native MCP (recommended — prompts on first use)

{
  "servers": {
    "quantum-openqasm-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@markusvankempen/quantum-openqasm-mcp"],
      "env": {
        "IBM_API_KEY": "${input:ibmApiKey}",
        "IBM_SERVICE_CRN": "${input:ibmServiceCrn}",
        "IBM_QUANTUM_ENDPOINT": "https://us-east.quantum-computing.cloud.ibm.com",
        "IBM_QUANTUM_BACKEND": "ibm_fez"
      }
    }
  },
  "inputs": [
    {
      "id": "ibmApiKey",
      "type": "promptString",
      "description": "IBM Cloud API Key (quantum.ibm.com → Account → API keys)",
      "password": true
    },
    {
      "id": "ibmServiceCrn",
      "type": "promptString",
      "description": "IBM Quantum Instance CRN (crn:v1:bluemix:public:quantum-computing:...)"
    }
  ]
}

VS Code stores prompted values securely — no secrets in the config file.

Bob & Antigravity

Use the same stdio block as Cursor. The Quantum OpenQASM Assistant extension can register this server in all supported IDEs with Quantum: Setup MCP.

More detail: Local MCP setup guide

MCP tools (10)

Tool	Description
check_credentials	Masked env var status + IBM IAM connectivity test
list_backends	List IBM Quantum backends — qubits, status, queue length
get_backend	Details for one backend
get_backend_configuration	Native gates and coupling map (ISA prep)
list_jobs	Recent jobs for your account
submit_qasm_job	Submit OpenQASM 2.0 via SamplerV2
get_job_status	Poll job status without full results
get_job_results	Measurement histogram and JSON counts
get_job_result	Combined status + results (legacy)
cancel_job	Cancel a queued or running job

Example AI prompts

• "Call check_credentials first to verify IBM Quantum setup."
• "Use quantum-openqasm-mcp list_backends and pick the shortest queue."
• "Submit this Bell-state OpenQASM circuit on ibm_fez with submit_qasm_job."
• "Poll get_job_status for job d8jftsk2upec739ngh4g until it completes, then show the histogram."

Minimal OpenQASM 2.0 example

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

Pass the circuit string to submit_qasm_job with provider: "ibm_quantum". Circuits should use the backend's native gate set (transpile first if needed).

Programmatic use

import { startQuantumMcpServer } from '@markusvankempen/quantum-openqasm-mcp';

await startQuantumMcpServer();

The server listens on stdio — suitable for MCP hosts that spawn child processes.

Publish (maintainers)

cd packages/quantum-openqasm-mcp
npm install
npm run pack:check          # dry-run npm tarball
npm publish --access public # npm first
npm run publish:mcp         # MCP Registry (requires: brew install mcp-publisher && mcp-publisher login github)

Bump version in package.json and server.json together before each release.

Related projects

Project	Description
MCP via npm (mode 3)	Setup guide — Cursor, VS Code, Bob, Antigravity
Quantum OpenQASM Assistant	VS Code / Cursor extension — Quantum Lab, histogram UI, diagnostics
OpenQASM primer	OpenQASM 2.0 language guide
Deployment scenarios	Local, Docker, Code Engine, remote SSE

Topics & keywords

mcp · mcp-server · model-context-protocol · quantum-computing · openqasm · qasm · ibm-quantum · quantum-circuit · quantum-hardware · job-polling · histogram · bell-state · cursor · vscode · claude-desktop · antigravity · ibm-bob · qiskit · sampler-v2 · ai-assistant · npx · stdio

License

Apache License 2.0 · opensource.org/licenses/Apache-2.0

Contributing & community

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• Issues

Author: Markus van Kempen
Email: [e-mail] · [e-mail]
Website: markusvankempen.github.io
No bug too small, no syntax too weird.