qiskit-mcp-server

An MCP server that gives Claude hands-on access to quantum computing via Qiskit. Ask Claude to build a circuit, simulate it, inspect the statevector, transpile it — and, if you have a free IBM Quantum account, run it on a real quantum computer.

Everything works fully offline out of the box: simulation runs locally on Qiskit Aer. No account, no token, no network. Real-hardware access is optional and switches on when you set an IBM_QUANTUM_TOKEN.

Tools

Tool	What it does
build_circuit	Build a circuit from a simple gate list, get back QASM + an ASCII diagram
run_simulation	Sample a circuit on the local Aer simulator — counts, probabilities, entropy
get_statevector	Exact amplitudes of a measurement-free circuit (up to 20 qubits)
list_backends	Local simulators always; real IBM devices when a token is configured
transpile_circuit	Depth and gate counts before/after transpiling, for a generic basis or a real device
submit_to_hardware	Run a circuit on a real IBM quantum computer (token required)
check_job_status	Poll a hardware job, get counts when it finishes (token required)

Circuits can be referenced three ways: by the circuit_id returned from build_circuit (in-memory, resets when the server restarts), as a portable OpenQASM 2 string, or as an inline gate-list spec. IBM job IDs live on IBM's side and survive restarts.

Setup

Requires Python 3.11+. With uv:

git clone https://github.com/TheNyansafo/qiskit-mcp-server.git
cd qiskit-mcp-server
uv sync

Or with plain pip: pip install . (add .[ibm] for the hardware path).

Claude Desktop

Add to claude_desktop_config.json (Settings → Developer → Edit Config). Use absolute paths — Desktop doesn't inherit your shell's PATH:

{
  "mcpServers": {
    "qiskit": {
      "command": "/absolute/path/to/uv",
      "args": ["run", "--directory", "/absolute/path/to/qiskit-mcp-server", "qiskit-mcp-server"]
    }
  }
}

Claude Code

claude mcp add qiskit -- uv run --directory /absolute/path/to/qiskit-mcp-server qiskit-mcp-server

Things to ask Claude once it's connected

• "Build a Bell state and simulate it with 2000 shots."
• "What's the statevector of a 3-qubit GHZ circuit?"
• "Build a circuit that puts qubit 0 in superposition, apply a Z, and show me the phases."
• "Transpile my Bell circuit to IBM's basis gates — how much deeper does it get?"
• "List the available backends."
• With a token: "Run this circuit on the least busy real quantum computer and check on the job."

Running on real hardware (optional, free)

IBM's Open Plan is free, needs no credit card, and includes roughly 10 minutes of real QPU time per month. Local Aer simulation is unlimited and doesn't touch your allowance.

1. Create an account at quantum.cloud.ibm.com
2. Copy your API key from the dashboard
3. Install the hardware extra: uv sync --extra ibm (or pip install '.[ibm]')
4. Put the token in the server's environment — for Claude Desktop, add to the server entry:

"env": { "IBM_QUANTUM_TOKEN": "your-api-key" }

Without a token, the hardware tools don't crash — they explain exactly this setup. (Qiskit also offers QiskitRuntimeService.save_account(), which writes the token to ~/.qiskit/qiskit-ibm.json in plaintext; the env var keeps credentials out of files. Nothing token-shaped is ever committed here — see .gitignore.)

Heads up: real devices queue behind other users, so submit_to_hardware returns a job ID immediately and you poll with check_job_status. Results from real hardware are noisy — seeing a few 01/10 counts from a Bell state is the hardware, not a bug.

Development

uv sync
uv run pytest

Tests cover circuit building, validation, simulation, statevectors, and transpilation — everything that runs offline. The token-gated tools are thin wrappers over qiskit-ibm-runtime and aren't unit-tested.

What's next

A Dyson sphere simulation — orbital mechanics and energy capture around a star.

License

MIT