qiskit-sim-mcp

一个模型上下文协议 (MCP) 服务器，允许 Claude Desktop 使用 Qiskit 和 Qiskit Aer 创建、可视化和模拟量子电路。

功能简介

连接到 Claude Desktop 后，您可以进行自然的对话，例如：

• “创建一个贝尔态并用 1024 次采样进行模拟”

• “向我展示 GHZ 电路图”

• “在高噪声下运行贝尔态并解释发生了什么变化”

• “根据此 QASM 字符串创建一个自定义电路”

Claude 将自动调用底层工具——无需手动调用。

特性

• 3 个工具：create_circuit、visualize_circuit、run_simulation

• 5 个预设电路：贝尔态 (Bell state)、GHZ-3、叠加态 (Superposition)、Deutsch-Jozsa、随机-4 (Random-4)

• 自定义 QASM：接受任何有效的 OpenQASM 2.0 字符串

• 噪声建模：通过去极化误差实现理想、低噪声 (p=0.001)、高噪声 (p=0.01)

• 1 个资源：resource://noise-presets — 列出可用的噪声配置

• 1 个提示词：simulate_walkthrough — 指导性对话模板

要求

• Python 3.13+

• Anaconda 或任何 Python 环境管理器

• Claude Desktop

设置

1. 克隆仓库

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

2. 安装依赖

pip install -e .

这将把 mcp[cli]、qiskit 和 qiskit-aer 安装到您的 Python 环境中。

3. 验证安装

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])
"

预期输出：

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

4. 使用 MCP Inspector 进行测试（可选）

uv run mcp dev src/quantum_mcp_demo/server.py

在浏览器中打开 http://localhost:6274。在连接到 Claude Desktop 之前，使用 Tools 选项卡手动调用每个工具。

5. 连接到 Claude Desktop

找到您的 Claude Desktop 配置文件：

在 mcpServers 对象中添加此条目：

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

注意： 将 /opt/anaconda3/bin/python 替换为您实际的 Python 路径。运行 which python 即可找到它。

6. 重启 Claude Desktop

完全退出 Claude Desktop（macOS 上为 Cmd+Q），然后重新打开。在新的对话中，聊天输入框中的锤子图标 (🔨) 表示 MCP 工具已加载。

使用示例

贝尔态模拟

“创建一个贝尔态电路，向我展示图表，然后分别在理想和高噪声下模拟 1024 次。”

Claude 将调用：

1. create_circuit(preset="bell") → 获取 circuit_id

2. visualize_circuit(circuit_id=...) → 显示 H + CNOT 门电路图

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") → 计数退化，出现 |01⟩ 和 |10⟩

自定义 QASM 电路

“运行此电路：OPENQASM 2.0; include "qelib1.inc"; qreg q[2]; creg c[2]; h q[0]; cx q[0],q[1]; measure q -> c;”

Claude 解析 QASM 字符串并通过相同的模拟流水线运行它。

噪声比较

“比较理想噪声与高噪声下的 GHZ 态——噪声对纠缠有什么影响？”

项目结构

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

预设电路

噪声预设

故障排除

Claude Desktop 不显示锤子图标

• 编辑配置后，完全退出并重新启动 Claude Desktop

• 检查配置 JSON 是否有效（没有多余的逗号）

• 验证 Python 路径：which python

python -m quantum_mcp_demo.server 失败

• 确保您已在项目根目录下运行 pip install -e .

• 确认 Python 版本：python --version（需要 3.13+）

运行 MCP Inspector 时端口冲突

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

模拟返回意外的计数

• 采样数不匹配会自动捕获并返回为 isError: true

• 如果看到错误，请尝试减少 shots（例如 512）