Qiskit MCP Server

Qiskit MCP 服务

一个 Model Context Protocol（MCP）服务，使用 Qiskit 的 pass managers 提供量子电路转译能力。此服务支持 AI 助手针对各种硬件目标优化量子电路。

功能

• 电路转译：使用可配置的优化级别（0-3）转译量子电路
• 预设基门：支持 IBM Eagle、IBM Heron、离子阱和其他基门集
• 拓扑支持：内置支持线性、环形、网格和自定义耦合映射
• 电路分析：无需转译即可分析电路复杂度
• 优化对比：比较所有优化级别的结果
• 双 API：同时支持异步（MCP）和同步（Jupyter、脚本）用法

前置条件

• Python 3.10 或更高版本
• uv 包管理器（推荐）或 pip

安装

从 PyPI 安装（发布后）

pip install qiskit-mcp-server

从源代码安装

# Clone the repository
git clone https://github.com/Qiskit/mcp-servers.git
cd mcp-servers/qiskit-mcp-server

# Install with uv
uv sync

# Or with pip
pip install -e .

快速开始

运行 MCP 服务

# With uv
uv run qiskit-mcp-server

# Or directly
qiskit-mcp-server

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

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

使用示例

异步用法（MCP 服务 / FastAPI）

from qiskit_mcp_server.transpiler import transpile_circuit

# Simple Bell state circuit (QASM2 - automatically detected)
qasm = """OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0], q[1];
measure q -> c;
"""

# Transpile with default settings (optimization level 2, QASM3 format)
result = await transpile_circuit(qasm)

# Transpile for IBM Heron processor
result = await transpile_circuit(
    qasm,
    optimization_level=3,
    basis_gates="ibm_heron",
    coupling_map="linear"
)

使用 QPY 格式

from qiskit import QuantumCircuit
from qiskit_mcp_server import dump_qpy_circuit
from qiskit_mcp_server.transpiler import transpile_circuit

# Create a circuit programmatically
qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])

# Convert to QPY (preserves exact parameters and metadata)
qpy_circuit = dump_qpy_circuit(qc)

# Transpile using QPY format
result = await transpile_circuit(qpy_circuit, circuit_format="qpy")
# Result includes transpiled circuit in QPY format (for chaining)
transpiled_qpy = result["transpiled_circuit"]["circuit_qpy"]

# Chain to another operation using QPY
result2 = await transpile_circuit(transpiled_qpy, circuit_format="qpy", optimization_level=3)

同步用法（脚本、Jupyter）

from qiskit_mcp_server.transpiler import transpile_circuit, analyze_circuit

# All async functions have a .sync attribute
result = transpile_circuit.sync(qasm, optimization_level=2)

# Analyze circuit without transpiling
analysis = analyze_circuit.sync(qasm)
print(f"Circuit depth: {analysis['circuit_info']['depth']}")
print(f"Two-qubit gates: {analysis['gate_categories']['two_qubit_gates']}")

比较优化级别

from qiskit_mcp_server.transpiler import compare_optimization_levels

# Compare all optimization levels (0-3) for your circuit
comparison = compare_optimization_levels.sync(qasm)

for level in range(4):
    result = comparison['optimization_results'][f'level_{level}']
    print(f"Level {level}: depth={result['depth']}, size={result['size']}")

LangChain 集成示例：

**注意：**运行 LangChain 示例需要安装以下依赖项：

pip install langchain langchain-mcp-adapters langchain-openai python-dotenv

import asyncio
import os
from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_mcp_adapters.tools import load_mcp_tools
from langchain_openai import ChatOpenAI
from dotenv import load_dotenv

# Load environment variables (OPENAI_API_KEY, etc.)
load_dotenv()

# Sample Bell state circuit
SAMPLE_BELL = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
h q[0];
cx q[0], q[1];
"""

async def main():
    # Configure MCP client
    mcp_client = MultiServerMCPClient({
        "qiskit": {
            "transport": "stdio",
            "command": "qiskit-mcp-server",
            "args": [],
            "env": {},
        }
    })

    # Use persistent session for efficient tool calls
    async with mcp_client.session("qiskit") as session:
        tools = await load_mcp_tools(session)

        # Create agent with LLM
        llm = ChatOpenAI(model="gpt-5.2", temperature=0)
        agent = create_agent(llm, tools)

        # Run a query
        response = await agent.ainvoke(f"Transpile this circuit for IBM Heron: {SAMPLE_BELL}")
        print(response)

asyncio.run(main())

如需了解更多 LLM 提供商（Anthropic、Google、Ollama、Watsonx）和详细示例（包括 Jupyter notebooks），请参阅 examples/ 目录。

API 参考

工具

工具	描述
transpile_circuit_tool	使用可配置的优化选项转译电路
analyze_circuit_tool	无需转译即可分析电路结构
compare_optimization_levels_tool	比较所有优化级别（0-3）
load_circuit_from_qasm_tool	从 OpenQASM 2.0 或 3.0 字符串加载电路，并返回 QPY 和元数据
export_circuit_to_qasm_tool	将 QPY 电路导出为 OpenQASM 2.0 或 3.0 格式
convert_qpy_to_qasm3_tool	将 base64 编码的 QPY 电路转换为 QASM3
convert_qasm3_to_qpy_tool	将 QASM3（或 QASM2）电路转换为 base64 编码的 QPY

资源

资源 URI	描述
qiskit://transpiler/info	转译器功能和文档
qiskit://transpiler/basis-gates	可用的基门预设
qiskit://transpiler/topologies	可用的耦合映射拓扑

核心函数

transpile_circuit(circuit, optimization_level=2, basis_gates=None, coupling_map=None, initial_layout=None, seed_transpiler=None, circuit_format="qasm3")

使用 Qiskit 的预设 pass manager 转译量子电路。

参数：

• circuit：以 QASM3 字符串、Base64 编码的 QPY 或 QASM2 字符串表示的量子电路（最多 100 个量子比特、10,000 个门）
• optimization_level：0-3（默认值：2）
  • 0：不进行优化，仅分解为基门（速度最快）
  • 1：使用默认布局进行轻度优化
  • 2：使用噪声感知布局进行中度优化（推荐）
  • 3：进行深度优化以获得最佳结果（大型电路可能很慢）
• basis_gates：门名称列表或预设（"ibm_default"、"ibm_heron" 等）
• coupling_map：边列表或拓扑名称（"linear"、"ring"、"grid"、"full"）
• initial_layout：物理量子比特索引列表（长度必须与电路量子比特数一致）
• seed_transpiler：用于确保结果可复现的随机种子
• circuit_format：输入电路的格式（"qasm3" 或 "qpy"）。默认值为 "qasm3"。指定 "qasm3" 时，也会将 QASM2 作为备用格式接受。

**返回值：**包含原始电路和转译后电路信息以及优化指标的字典

**注意：**对于量子比特数超过 20 或门数超过 500 的电路，3 级优化可能非常耗时。建议使用 2 级优化，以更快获得良好效果。

analyze_circuit(circuit, circuit_format="qasm3")

分析电路结构和复杂度。

**返回值：**包含门计数、深度和分类（单量子比特门／双量子比特门／多量子比特门）的字典

compare_optimization_levels(circuit, circuit_format="qasm3")

比较所有优化级别下的转译结果。

**返回值：**比较 0-3 级优化结果的深度、大小和门的字典

电路格式支持

服务支持以下两种输入电路格式：

格式	说明
qasm3	OpenQASM 3.0 字符串（支持 QASM2 备用格式）。人类可读的文本格式。
qpy	Base64 编码的 QPY 二进制格式。可保留精确参数和元数据。

**QPY 输出：**所有工具都以 QPY 格式（Base64 编码）返回电路，以便在串联使用工具／服务时保证精度。

格式选择建议：

• QASM3（输入）：适合人类可读的电路和初始输入
• QPY（输入／输出）：适合在串联使用工具／服务时保留精确数值参数

将 QPY 转换为人类可读的 QASM3

若要以人类可读的格式查看 QPY 电路输出，请使用 qpy_to_qasm3 实用工具：

from qiskit_mcp_server import qpy_to_qasm3
from qiskit_mcp_server.transpiler import transpile_circuit

# Transpile a circuit (returns QPY format)
result = transpile_circuit.sync(qasm_circuit, optimization_level=2)
qpy_output = result["transpiled_circuit"]["circuit_qpy"]

# Convert to human-readable QASM3
conversion = qpy_to_qasm3(qpy_output)
if conversion["status"] == "success":
    print(conversion["qasm3"])

将 QASM3 转换为 QPY

若要将 QASM 电路转换为 QPY 格式（以便在串联使用工具时保留完整信息），请使用 qasm3_to_qpy：

from qiskit_mcp_server import qasm3_to_qpy

qasm_circuit = '''
OPENQASM 3.0;
include "stdgates.inc";
qubit[2] q;
h q[0];
cx q[0], q[1];
'''

# Convert to QPY format
result = qasm3_to_qpy(qasm_circuit)
if result["status"] == "success":
    qpy_string = result["circuit_qpy"]
    # Use qpy_string with tools that accept QPY input

可用的基门集

预设	门	说明
ibm_eagle	id, rz, sx, x, ecr, reset	IBM Eagle r3（127 个量子比特，使用 ECR）
ibm_heron	id, rz, sx, x, cz, reset	IBM Heron（133-156 个量子比特，使用 CZ）
ibm_legacy	id, rz, sx, x, cx, reset	较早期的 IBM 系统（使用 CX）

你也可以提供自定义门名称列表，以适用于其他硬件目标。

可用拓扑

拓扑	说明
linear	链式连接（量子比特 i ↔ i+1）
ring	带首尾相连的线性连接
grid	二维网格连接
heavy_hex	IBM heavy-hex 拓扑（Eagle／Heron 架构）
full	全连接

限制和性能

电路大小限制

为确保性能稳定，服务设有以下限制：

限制	默认值	环境变量
最大量子比特数	100	QISKIT_MCP_MAX_QUBITS
最大门数	10,000	QISKIT_MCP_MAX_GATES

超过这些限制的电路将返回包含详细说明的错误。

你可以通过环境变量覆盖这些限制：

# Allow up to 200 qubits and 50,000 gates
export QISKIT_MCP_MAX_QUBITS=200
export QISKIT_MCP_MAX_GATES=50000

性能建议

优化级别	使用场景	性能
0	快速迭代、调试	最快
1	开发、原型设计	快
2	生产环境使用（推荐）	均衡
3	关键应用、小型电路	最慢

提示：

• 大多数使用场景建议使用级别 2（质量与速度的最佳平衡）
• 仅当电路质量至关重要且电路较小（<20 个量子比特、<500 个门）时，才使用级别 3
• 快速原型设计和开发时使用级别 0 或 1
• compare_optimization_levels 工具有助于为特定电路确定最佳级别

转译阶段

Qiskit 转译器会通过六个阶段处理电路：

1. init：将多量子比特门分解为 1 和 2 量子比特操作
2. layout：将虚拟量子比特映射到物理量子比特
3. routing：为适配硬件连接性插入 SWAP 门
4. translation：转换为目标基门
5. optimization：减少门数量和电路深度
6. scheduling：添加计时和延迟指令

测试

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src --cov-report=term-missing

# Run specific test class
uv run pytest tests/test_transpiler.py::TestTranspileCircuit -v

开发

# Install dev dependencies
uv sync --group dev --group test

# Run linting
uv run ruff check src tests
uv run ruff format --check src tests

# Run type checking
uv run mypy src

# Run all checks
./run_tests.sh

贡献

欢迎贡献！请参阅仓库根目录中的 CONTRIBUTING.md 指南。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。