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

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

Next project on this account: a Dyson sphere simulation — orbital mechanics and energy capture around a star, built to the same drop-in-and-run standard. Watch this space.

License

MIT