quantum-vibecoding-mcp

Model Context Protocol servers that let Claude run real quantum experiments on real hardware through natural language.

Three servers ship in one package:

Install

The recommended path uses uvx — no manual install needed.

Claude Code (CLI / Desktop)

Add to your .mcp.json (project-level) or ~/.claude.json (global):

{
  "mcpServers": {
    "qi-circuits": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "quantum-vibecoding-mcp[qi]", "qvc-qi"]
    }
  }
}

For all three servers:

{
  "mcpServers": {
    "qi-circuits": {
      "command": "uvx",
      "args": ["--from", "quantum-vibecoding-mcp[qi]", "qvc-qi"]
    },
    "ibm-quantum": {
      "command": "uvx",
      "args": ["--from", "quantum-vibecoding-mcp[ibm]", "qvc-ibm"]
    },
    "qrng": {
      "command": "uvx",
      "args": ["--from", "quantum-vibecoding-mcp[qi]", "qvc-qrng"]
    }
  }
}

Manual install

pip install "quantum-vibecoding-mcp[all]"
qvc-qi   # then point claude at this binary

Authentication

Hello world

After config, prompt Claude:

Submit a Bell-state circuit to QI's local emulator with 1024 shots and show me the histogram.

Claude calls qi_run_local, you see {"00": ~512, "11": ~512}.

Tools

qvc-qi exposes: qi_list_backends, qi_submit_circuit, qi_check_job, qi_get_results, qi_run_local.

qvc-ibm exposes: ibm_list_backends, ibm_submit_circuit, ibm_check_job, ibm_get_results.

qvc-qrng exposes: quantum_random_int, quantum_coin_flip, quantum_random_hex, quantum_dice_roll, and friends.

Hardware notes

Tuna-9 (Quantum Inspire) native gate set: CZ, Ry, Rz, X. Pass compile_stage="routing" to let QI's compiler decompose for you.

Bitstrings are MSB-first across the board — qubit 0 is the leftmost character. See the Quantum Vibecoding paper §3.4 for the conventions and silent-bug list.

Development

git clone https://github.com/JDerekLomas/quantuminspire.git
cd quantuminspire/mcp-servers
pip install -e ".[all]"

License

MIT.