# 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](https://www.anaconda.com/) or any Python environment manager
- [Claude Desktop](https://claude.ai/download)

## Setup

### 1. Clone the Repository

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

### 2. Install Dependencies

```bash
pip install -e .
```

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

### 3. Verify the Installation

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

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

```json
{
  "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**
```bash
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