# qiskit-mcp-server

An MCP server that gives Claude hands-on access to quantum computing via [Qiskit](https://www.ibm.com/quantum/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](https://github.com/Qiskit/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](https://docs.astral.sh/uv/):

```bash
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:

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

### Claude Code

```bash
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](https://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:

```json
"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

```bash
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_id`s** 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