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

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.

Related MCP server: mcp-qiskit

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

28 tests, all passing offline against Qiskit 2.5 / Aer. They cover circuit building, validation, simulation, statevectors, and transpilation — everything that runs without a token. The token-gated tools (submit_to_hardware, check_job_status) are thin wrappers over qiskit-ibm-runtime and aren't unit-tested.

If uv run pytest reports ModuleNotFoundError: No module named 'qiskit_mcp', the virtualenv is stale — usually because the project directory was moved after the venv was created. rm -rf .venv && uv sync fixes it.

What's next

• Noise models. run_simulation is noiseless today; Aer can simulate a real device's noise profile, which would let you compare ideal vs. realistic results without burning hardware queue time. Highest value per unit of effort.

• Multi-circuit batching for submit_to_hardware — real-device queue time dominates, so submitting several circuits in one job is a large practical win.

• Persist circuit_ids across restarts. They're in-memory now, so a server restart loses references mid-conversation.

• Cover the IBM path with recorded/mocked runtime responses, so the token-gated tools aren't entirely untested.

License

MIT