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

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

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