qiskit-sim-mcp

A Model Context Protocol (MCP) server that lets Claude Desktop create, visualize, and simulate quantum circuits using Qiskit and Qiskit Aer.

What It Does

Once connected to Claude Desktop, you can have natural conversations like:

• "Create a Bell state and simulate it with 1024 shots"
• "Show me the GHZ circuit diagram"
• "Run the Bell state with high noise and explain what changed"
• "Create a custom circuit from this QASM string"

Claude will call the underlying tools automatically — no manual tool invocation needed.

Features

• 3 Tools: create_circuit, visualize_circuit, run_simulation
• 5 Preset Circuits: Bell state, GHZ-3, Superposition, Deutsch-Jozsa, Random-4
• Custom QASM: Accepts any valid OpenQASM 2.0 string
• Noise Modeling: Ideal, low noise (p=0.001), high noise (p=0.01) via depolarizing error
• 1 Resource: resource://noise-presets — lists available noise configurations
• 1 Prompt: simulate_walkthrough — guided conversation template

Requirements

• Python 3.13+
• Anaconda or any Python environment manager
• Claude Desktop

Setup

1. Clone the Repository

git clone <repo-url>
cd qiskit-sim-mcp

2. Install Dependencies

pip install -e .

This installs mcp[cli], qiskit, and qiskit-aer into your Python environment.

3. Verify the Installation

python -c "
import asyncio
from quantum_mcp_demo.server import mcp

tools    = asyncio.run(mcp.list_tools())
resources = asyncio.run(mcp.list_resources())
prompts  = asyncio.run(mcp.list_prompts())

print('Tools:',     [t.name for t in tools])
print('Resources:', [r.uri  for r in resources])
print('Prompts:',   [p.name for p in prompts])
"

Expected output:

Tools: ['create_circuit', 'visualize_circuit', 'run_simulation']
Resources: [AnyUrl('resource://noise-presets')]
Prompts: ['simulate_walkthrough']

4. Test with MCP Inspector (Optional)

uv run mcp dev src/quantum_mcp_demo/server.py

Open http://localhost:6274 in your browser. Use the Tools tab to call each tool manually before connecting to Claude Desktop.

5. Connect to Claude Desktop

Find your Claude Desktop config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Add this entry inside the mcpServers object:

{
  "mcpServers": {
    "qiskit-sim-mcp": {
      "command": "/opt/anaconda3/bin/python",
      "args": [
        "-m",
        "quantum_mcp_demo.server"
      ]
    }
  }
}

Note: Replace /opt/anaconda3/bin/python with your actual Python path. Run which python to find it.

6. Restart Claude Desktop

Quit Claude Desktop completely (Cmd+Q on macOS), then reopen it. In a new conversation, the hammer icon (🔨) in the chat input confirms MCP tools are loaded.

Usage Examples

Bell State Simulation

"Create a Bell state circuit, show me the diagram, then simulate it 1024 times with ideal and high noise."

Claude will call:

1. create_circuit(preset="bell") → gets a circuit_id
2. visualize_circuit(circuit_id=...) → shows the H + CNOT gate diagram
3. run_simulation(circuit_id=..., shots=1024, noise_preset="ideal") → ~50% |00⟩, ~50% |11⟩
4. run_simulation(circuit_id=..., shots=1024, noise_preset="high_noise") → degraded counts, |01⟩ and |10⟩ appear

Custom QASM Circuit

"Run this circuit: OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;"

Claude parses the QASM string and runs it through the same simulation pipeline.

Noise Comparison

"Compare the GHZ state under ideal vs high noise — what does the noise do to the entanglement?"

Project Structure

src/quantum_mcp_demo/
├── server.py              # MCP server entry point
├── circuits/
│   ├── presets.py         # 5 named preset circuits
│   └── store.py           # In-memory circuit storage (UUID-keyed)
├── tools/
│   ├── create_circuit.py  # Tool: create from preset or QASM
│   ├── visualize.py       # Tool: HTML diagram + gate JSON
│   └── simulate.py        # Tool: AerSimulator + noise modeling
├── resources/
│   └── noise_presets.py   # Resource: noise configuration list
├── prompts/
│   └── walkthrough.py     # Prompt: guided simulation conversation
└── utils/
    ├── serialization.py   # numpy → Python int conversion
    └── errors.py          # MCP error response builder

Preset Circuits

Preset	Qubits	Demonstrates
bell	2	Entanglement — 50/50 split on |00⟩ and |11⟩
ghz_3	3	Multi-qubit entanglement
superposition	1	Equal superposition via Hadamard
deutsch_jozsa	3	Quantum algorithm — interference
random_4	4	Noise stress test — fixed-seed random gates

Noise Presets

Preset	Depolarizing p	Description
ideal	none	Perfect simulation
low_noise	0.001	Realistic near-term device
high_noise	0.01	Aggressive noise — visible degradation

Troubleshooting

Claude Desktop doesn't show the hammer icon

• Quit and fully relaunch Claude Desktop after editing the config
• Check the config JSON is valid (no trailing commas)
• Verify the Python path: which python

python -m quantum_mcp_demo.server fails

• Make sure you ran pip install -e . from the project root
• Confirm Python version: python --version (needs 3.13+)

Port conflict when running MCP Inspector

kill -9 $(lsof -t -i :6274) 2>/dev/null; kill -9 $(lsof -t -i :6277) 2>/dev/null

Simulation returns unexpected counts

• Shot count mismatches are caught automatically and returned as isError: true
• Try reducing shots (e.g. 512) if you see errors