mcp-qiskit

mcp-qiskit

通过模型上下文协议公开 Qiskit 2.3.1 量子计算功能的 MCP 服务。借助标准化的 MCP 工具和资源，让大模型能够创建、操作和执行量子电路。

mcp-name: io.github.daedalus/mcp-qiskit

概述

本项目提供一个模型上下文协议（MCP）服务，向大语言模型（LLM）公开 Qiskit 量子计算功能。它让 AI 助手能够：

• 创建和操作量子电路
• 在量子模拟器或真实后端上执行电路
• 分析电路属性（深度、门、操作）
• 以各种格式可视化电路
• 管理量子后端

为什么使用它？

• LLM 集成：让 AI 助手无需外部工具即可执行量子计算任务
• 标准化接口：MCP 为量子操作提供一致的、基于工具的接口
• 兼容 Qiskit 2.3.1：专为 Qiskit 2.3.1 设计，支持其所有功能
• 可扩展：可轻松添加新工具或后端

安装

前置条件

• Python 3.11 或更高版本
• Qiskit 2.3.1
• 正在运行的 MCP 客户端（Claude Desktop、Cursor 等）

从 PyPI 安装

pip install mcp-qiskit[qiskit]

[qiskit] extra 会安装所需的 Qiskit 依赖项。还提供其他 extras：

# Install with development dependencies
pip install mcp-qiskit[dev,test]

# Install with MCP server dependencies
pip install mcp-qiskit[mcp]

从源代码安装

git clone https://github.com/daedalus/mcp-qiskit.git
cd mcp-qiskit
pip install -e ".[all]"

快速入门

作为 Python 库使用

from mcp_qiskit import create_quantum_circuit, add_gate, add_gates, add_measurement, run_circuit

# Create a 2-qubit circuit with 2 classical bits
circuit = create_quantum_circuit(2, 2)

# Apply a Hadamard gate on qubit 0
circuit = add_gate(circuit, "h", [0])

# Apply CNOT gate (control: qubit 0, target: qubit 1)
circuit = add_gate(circuit, "cx", [0, 1])

# Or add multiple gates at once with add_gates
circuit = add_gates(circuit, [
    {"gate": "h", "qubits": [0]},
    {"gate": "cx", "qubits": [0, 1]},
])

# Measure all qubits
circuit = add_measurement(circuit, [0, 1])

# Execute on Aer simulator
result = run_circuit(circuit, "aer_simulator", shots=1024)
print(f"Measurement results: {result['counts']}")

作为 MCP 服务使用

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-qiskit": {
      "command": "mcp-qiskit",
      "env": {}
    }
  }
}

Cursor

在 MCP Servers 下的 Cursor 设置中添加：

{
  "mcpServers": {
    "mcp-qiskit": {
      "command": "mcp-qiskit",
      "args": []
    }
  }
}

其他 MCP 客户端

# Run as stdio server
mcp-qiskit

# Or use the Python module directly
python -m mcp_qiskit

MCP 工具参考

电路创建工具

create_quantum_circuit_tool

创建一个空量子电路，并指定量子比特和经典比特的数量。

参数：

• num_qubits（int）：量子比特数量
• num_classical_bits（int）：用于测量的经典比特数量

**返回值：**表示电路的字典

示例：

circuit = create_quantum_circuit_tool(num_qubits=3, num_classical_bits=3)
# Returns: {"num_qubits": 3, "num_clbits": 3, "operations": [], "name": "circuit"}

add_gate_tool

向电路添加量子门。此工具会在多次调用之间保留电路状态。

参数：

• circuit（dict，可选）：要修改的电路。如果为 None，则自动创建一个包含 8 个量子比特和 8 个经典比特的新电路。
• gate_name（str）：门的名称（例如，“h”、“x”、“cx”、“rx”）
• qubits（list[int]）：要应用门的量子比特索引列表。可以是单个量子比特（例如，[0]），也可以是多个量子比特（例如，[0, 1, 2, 3]）。如果为单量子比特门指定了多个量子比特，则会将该门应用于每个量子比特。
• params（list[float]，可选）：参数化门的参数

支持的门：

• 单量子比特：h、x、y、z、s、t、sdg、tdg、i、id
• 参数化：rx、ry、rz、u1、u2、u3、p
• 多量子比特：cx、cy、cz、swap
• 多控门：mcx、mct、mcp、ccx、toffoli、c3x、c3sx、c4x
• 专用门：rxx、ryy、rzz、ch、cswap、cu、crx、cry、crz

状态维护模式： 始终将上一次调用返回的电路传入，以维护状态：

# Option 1: Pass circuit explicitly
circuit = add_gate_tool(circuit=None, gate_name="h", qubits=[0])  # Creates new circuit
circuit = add_gate_tool(circuit=circuit, gate_name="x", qubits=[1])  # Appends

# Option 2: Use returned circuit
circuit = add_gate_tool(None, "h", [0])
circuit = add_gate_tool(circuit, "cx", [0, 1])
circuit = add_gate_tool(circuit, "rx", [0], [0.5])

对多个量子比特应用单量子比特门： 同时对多个量子比特应用单量子比特门（如 h、x、y、z 等）时，请使用量子比特索引列表：

# Apply H gate to qubits 0, 1, 2, 3 simultaneously
circuit = add_gate_tool(circuit, "h", [0, 1, 2, 3])

# Apply X gate to qubits 4, 5, 6, 7 simultaneously  
circuit = add_gate_tool(circuit, "x", [4, 5, 6, 7])

add_gates_tool

在一次调用中向电路添加多个量子门。此工具会在多次调用之间保留电路状态，并减少所需的工具调用次数。

参数：

• circuit (dict，可选)：要修改的电路。如果为 None，则自动创建一个包含 8 个量子位和 8 个经典位的新电路。
• gates (list[dict])：门规格列表，每项包含：
  • gate (str)：门的名称（例如 "h"、"x"、"cx"、"rx"）
  • qubits (list[int])：要应用该门的量子位索引
  • params (list[float]，可选)：参数化门的参数

示例：

# Add multiple gates in one call (reduces tool calls)
gates = [
    {"gate": "h", "qubits": [0]},
    {"gate": "cx", "qubits": [0, 1]},
    {"gate": "x", "qubits": [2]},
]
circuit = add_gates_tool(circuit=None, gates=gates)

# Can be chained to maintain state
circuit = add_gates_tool(None, [{"gate": "h", "qubits": [0, 1]}])
circuit = add_gates_tool(circuit, [{"gate": "rz", "qubits": [0], "params": [0.5]}])

add_measurement_tool

向量子位添加测量操作。此工具会在多次调用之间保留电路状态。

参数：

• circuit (dict，可选)：要修改的电路。如果为 None，则自动创建一个包含 8 个量子位和 8 个经典位的新电路。
• qubits (list[int])：要测量的量子位索引
• clbits (list[int]，可选)：用于存储结果的经典位索引

示例：

# Maintain state between calls
circuit = add_measurement_tool(circuit=None, qubits=[0, 1])           # Creates new circuit
circuit = add_measurement_tool(circuit=circuit, qubits=[2])          # Appends measurement

# Or use returned circuit
circuit = add_measurement_tool(None, [0, 1])           # Measure q0->c0, q1->c1
circuit = add_measurement_tool(circuit, [0, 1], [1, 0]) # Measure q0->c1, q1->c0

分析工具

get_circuit_depth_tool

返回电路的深度（层数）。

参数：

• circuit (dict)：要分析的电路

**返回值：**表示电路深度的整数

list_available_gates_tool

列出 Qiskit 中所有可用的量子门。

**返回值：**门名称字符串列表

get_gate_definition_tool

获取量子门的详细信息。

参数：

• gate_name (str)：门的名称

**返回值：**包含门属性的字典：

• name：门名称
• num_qubits：该门作用的量子位数量
• num_parameters：参数数量（固定门为 0）
• params：参数值列表

可视化工具

draw_circuit_tool

以多种格式呈现电路。

参数：

• circuit (dict)：要绘制的电路
• output_format (str)：输出格式——"ascii"、"text"、"mpl"、"latex"

**返回值：**电路的字符串表示

示例输出（ASCII）：

     ┌───┐
q_0: ┤ H ├──■──
     └───┘┌─┴─┐
q_1: ────┤ X ├
         └───┘
c: 2/═══════╪═══
         0   1

后端工具

list_backends_tool

列出可用的量子后端。

参数：

• filters (dict，可选)：筛选条件（例如，{"status": "ONLINE"}）

**返回值：**后端信息字典列表

get_backend_status_tool

获取后端的状态信息。

参数：

• backend_name (str)：后端名称

**返回值：**包含以下内容的字典：

• name：后端名称
• status：状态（ONLINE/OFFLINE）
• num_qubits：量子位数量

get_backend_configuration_tool

获取后端的详细配置。

参数：

• backend_name (str)：后端名称

**返回值：**包含以下内容的字典：

• name：后端名称
• num_qubits：量子位数量
• coupling_map：量子位连接关系（如适用）
• basis_gates：可用基门列表
• max_shots：允许的最大 shots 数

执行工具

run_circuit_tool

执行单个量子电路。

参数：

• circuit (dict)：要执行的电路
• backend_name (str，可选)：后端名称（默认值："aer_simulator"）
• shots (int，可选)：测量次数（默认值：1024）
• seed (int，可选)：用于确保可复现性的随机种子

**返回值：**包含以下内容的字典：

• status："COMPLETED" 或错误消息
• backend：使用的后端
• shots：测量次数
• counts：测量结果计数（如果 shots > 0）
• statevector：状态向量（如果 shots=None）
• time_taken：执行时间（秒）

示例：

result = run_circuit_tool(circuit, "aer_simulator", shots=1000, seed=42)
# Returns: {"status": "COMPLETED", "counts": {"00": 512, "11": 488}, ...}

run_circuits_tool

批量执行多个电路。

参数：

• circuits (list[dict])：要执行的电路列表
• backend_name (str，可选)：后端名称
• shots (int，可选)：测量次数
• seed (int，可选)：随机种子

**返回值：**结果字典列表

示例：

circuits = [circuit1, circuit2, circuit3]
results = run_circuits_tool(circuits, shots=100)
# Returns list of 3 result dictionaries

transpile_circuit_tool

转译电路以进行优化或适配特定后端。

参数：

• circuit (dict)：要转译的电路
• optimization_level (int，可选)：0-3（默认值：1）
• basis_gates (list[str]，可选)：目标基门

**返回值：**转译后的电路字典

示例：

transpiled = transpile_circuit_tool(circuit, optimization_level=2)

MCP 资源

resource://backends

提供可用量子后端列表。该列表会根据可用提供方动态更新。

resource://gates

提供 Qiskit 中所有可用量子门的列表。

使用示例

创建 Bell 态

# Create 2-qubit circuit
circuit = create_quantum_circuit(2, 2)

# Create Bell state: |Φ+⟩ = (|00⟩ + |11⟩) / √2
circuit = add_gate(circuit, "h", [0])
circuit = add_gate(circuit, "cx", [0, 1])
circuit = add_measurement(circuit, [0, 1])

# Execute
result = run_circuit(circuit, "aer_simulator", shots=1000)
print(result["counts"])  # Approximately {"00": 500, "11": 500}

运行 Grover 算法

def create_grover_circuit(num_qubits, iterations):
    circuit = create_quantum_circuit(num_qubits, num_qubits)
    
    # Initial superposition
    for i in range(num_qubits):
        circuit = add_gate(circuit, "h", [i])
    
    # Grover iterations
    for _ in range(iterations):
        # Oracle (marked state |11...1⟩)
        for i in range(num_qubits):
            circuit = add_gate(circuit, "x", [i])
        circuit = add_gate(circuit, "cx", list(range(num_qubits - 1)), [num_qubits - 1])
        for i in range(num_qubits):
            circuit = add_gate(circuit, "x", [i])
        
        # Diffusion operator
        for i in range(num_qubits):
            circuit = add_gate(circuit, "h", [i])
        for i in range(num_qubits):
            circuit = add_gate(circuit, "x", [i])
        circuit = add_gate(circuit, "cx", list(range(num_qubits - 1)), [num_qubits - 1])
        for i in range(num_qubits):
            circuit = add_gate(circuit, "x", [i])
        for i in range(num_qubits):
            circuit = add_gate(circuit, "h", [i])
    
    # Measurement
    circuit = add_measurement(circuit, list(range(num_qubits)))
    return circuit

circuit = create_grover_circuit(3, 1)
result = run_circuit(circuit, "aer_simulator", shots=1000)

绘制和分析电路

circuit = create_quantum_circuit(2, 2)
circuit = add_gate(circuit, "h", [0])
circuit = add_gate(circuit, "cx", [0, 1])
circuit = add_measurement(circuit, [0, 1])

# Get depth
depth = get_circuit_depth(circuit)
print(f"Circuit depth: {depth}")

# List gates
gates = list_available_gates()
print(f"Available gates: {len(gates)}")

# Draw circuit
ascii_output = draw_circuit(circuit, "ascii")
print(ascii_output)

运行 Shor 算法

from mcp_qiskit import (
    create_quantum_circuit,
    add_gate,
    add_measurement,
    run_circuit,
)

def build_shor_circuit(N=15, a=2, n_count=8):
    """Build Shor's factoring circuit for N=15 using MCX gates."""
    n = N.bit_length()
    circuit = create_quantum_circuit(n_count + n, n_count)
    
    # Superposition on first register
    for i in range(n_count):
        circuit = add_gate(circuit, "h", [i])
    
    # Initialize second register to |1>
    circuit = add_gate(circuit, "x", [n_count])
    
    # Controlled modular exponentiation using MCX
    for i in range(n_count):
        power = pow(a, 2**i, N)
        for j in range(n):
            if (power >> j) & 1:
                circuit = add_gate(circuit, "mcx", [[i], [n_count + j]])
    
    # Inverse QFT (simplified)
    for i in range(n_count - 1, -1, -1):
        for j in range(i + 1, n_count):
            circuit = add_gate(circuit, "cp", [i, j], [3.14159 / (2 ** (j - i))])
        circuit = add_gate(circuit, "h", [i])
    
    # Measure first register
    circuit = add_measurement(circuit, list(range(n_count)))
    return circuit

# Run Shor's algorithm to factor 15
circuit = build_shor_circuit(N=15, a=2, n_count=8)
result = run_circuit(circuit, "aer_simulator", shots=1000)
print(f"Results: {result['counts']}")

完整实现（包含因数提取）请参见 examples/shor_example.py。

使用 MCP Qiskit 工具运行 Shor 算法

使用 MCP Qiskit 服务工具构建 Shor 算法电路，对 N=15 进行因数分解：

# Step 1: Create an 8-qubit circuit with 4 classical bits
circuit = create_quantum_circuit_tool(num_qubits=8, num_classical_bits=4)

# Step 2: Apply H gates to qubits 0-3 (superposition)
circuit = add_gate_tool(circuit=circuit, gate_name="h", qubits=[0, 1, 2, 3])

# Step 3: Apply X gates to qubits 4-7 (initialize to |1⟩)
circuit = add_gate_tool(circuit=circuit, gate_name="x", qubits=[4, 5, 6, 7])

# Step 4: Add modular exponentiation using CP gates
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[0, 4], params=[3.14159/2])  # CP(π/2)
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[1, 6], params=[3.14159/4])  # CP(π/4)
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[2, 4], params=[3.14159])    # CP(π)
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[3, 4], params=[3.14159])    # CP(π)

# Step 5: Apply inverse QFT using H and CP gates (reverse order)
# CP(π/4) on [2,3], CP(π/2) on [1,2], CP(π) on [0,1]
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[2, 3], params=[3.14159/4])
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[1, 2], params=[3.14159/2])
circuit = add_gate_tool(circuit=circuit, gate_name="cp", qubits=[0, 1], params=[3.14159])
# H gates in reverse order
circuit = add_gate_tool(circuit=circuit, gate_name="h", qubits=[3, 2, 1, 0])

# Step 6: Measure qubits 0-3
circuit = add_measurement_tool(circuit=circuit, qubits=[0, 1, 2, 3])

# Step 7: Run on aer_simulator
result = run_circuit_tool(circuit=circuit, backend_name="aer_simulator", shots=1024, seed=42)
print(f"Measurement results: {result['counts']}")

# Extract factors from the measurement result:
# 1. Compute the phase from measurement outcome
# 2. Find order r via continued fractions
# 3. Calculate gcd(a^(r/2) ± 1, N)
# Expected: Factorization of 15 = 3 × 5

架构

mcp-qiskit/
├── src/mcp_qiskit/
│   ├── __init__.py          # Package exports
│   ├── __main__.py          # CLI entry point
│   ├── _circuit.py           # Circuit operations
│   ├── _backend.py           # Backend management
│   ├── _execution.py         # Circuit execution
│   └── _mcp.py               # MCP server definition
├── tests/                    # Test suite
├── SPEC.md                   # Project specification
└── README.md                 # This file

模块职责

• _circuit.py：量子电路创建、量子门、测量、可视化
• _backend.py：后端发现、状态、配置
• _execution.py：电路执行、转译
• _mcp.py：FastMCP 服务定义、工具注册

要求

• Python 3.11+
• qiskit >= 2.3.1
• qiskit-aer >= 0.14.0
• fastmcp >= 2.0

开发

设置

git clone https://github.com/daedalus/mcp-qiskit.git
cd mcp-qiskit
pip install -e ".[all]"

运行测试

pytest -v

代码质量

# Format code
ruff format src/ tests/

# Lint
ruff check src/ tests/

# Type check
mypy src/

Pre-commit 钩子

pre-commit install

故障排查

API 密钥和凭据

此软件包支持两种类型的后端：

1. Aer 模拟器（默认）——在本地运行，无需 API 密钥
2. IBM Quantum——需要 IBM Quantum API 令牌

使用 IBM Quantum 后端

若要使用 IBM Quantum 后端，需要提供 API 令牌：

选项 1：环境变量

export IBM_QUANTUM_TOKEN="your_api_token_here"

或在 Python 代码中：

import os
os.environ["IBM_QUANTUM_TOKEN"] = "your_api_token_here"

选项 2：通过 Qiskit 保存凭据

from qiskit_ibm_provider import IBMProvider

# Save your account (only needs to be done once)
IBMProvider.save_account(token="your_api_token_here", overwrite=True)

# Now you can use IBM backends
from mcp_qiskit._backend import list_backends, get_backend

backends = list_backends()  # Will include IBM backends
backend = get_backend("ibm_qasm_simulator")  # Or specific IBM backend

获取 IBM Quantum 令牌：

1. 在 IBM Quantum 创建账户
2. 前往 Account > My Tokens
3. 复制 API 令牌

MCP 服务的环境变量：

作为 MCP 服务运行时，请在启动前设置环境变量：

export IBM_QUANTUM_TOKEN="your_token"
mcp-qiskit

或在 MCP 客户端配置中设置：

{
  "mcpServers": {
    "mcp-qiskit": {
      "command": "mcp-qiskit",
      "env": {
        "IBM_QUANTUM_TOKEN": "your_token_here"
      }
    }
  }
}

未找到后端

如果出现“Backend not found”，请确认后端名称正确：

# List available backends
backends = list_backends()
print([b["name"] for b in backends])

导入错误

确保已正确安装 Qiskit：

pip install qiskit==2.3.1 qiskit-aer

MCP 连接问题

确认服务正在运行：

mcp-qiskit --help

许可证

MIT 许可证——详见 LICENSE 文件。

贡献

欢迎贡献！请在 GitHub 上提出问题或提交 PR。

相关项目

• Qiskit - 量子计算 SDK
• FastMCP - MCP 框架
• Model Context Protocol - 协议规范