Qiskit IBM Transpiler MCP Server

qiskit-ibm-transpiler-mcp-server

用于 Qiskit 转译器的 MCP 服务。它使用 QASM 3.0 作为输入/输出工具格式，支持 AI routing、AI Clifford 合成、AI Linear Function 合成、AI Permutation 合成和 AI Pauli Network 合成。

功能

• AI 转译器：在 routing 和 synthesis pass 中执行基于机器学习的优化
• QPY 输出：返回 base64 编码的 QPY 格式，确保串联工具/服务时的精度
• 双输入格式：同时接受 QASM 3.0 字符串和 base64 编码的 QPY 作为输入

先决条件

• python>=3.10 and <3.14
• qiskit-ibm-transpiler==0.15.0
• fastmcp>=2.12.4

安装

从 PyPI 安装

最简单的安装方式是使用 pip：

pip install qiskit-ibm-transpiler-mcp-server

从源代码安装

本项目建议使用 uv 管理虚拟环境和依赖项。如果尚未安装 uv，请参阅 https://docs.astral.sh/uv/getting-started/installation/ 中的说明。

使用 uv 设置项目

1. 初始化或同步项目：

   # This will create a virtual environment and install dependencies
   uv sync
   

快速入门

运行服务

uv run qiskit-ibm-transpiler-mcp-server

服务将启动并监听 MCP 连接。

同步用法（脚本、Jupyter）

对于不支持异步操作的框架：

from qiskit_ibm_transpiler_mcp_server.qta import (
    ai_routing,
    ai_clifford_synthesis
)
from qiskit_ibm_transpiler_mcp_server.utils import setup_ibm_quantum_account

from dotenv import load_dotenv

load_dotenv()

# 1. Load Quantum Circuit to be synthesized as QASM 3.0 string
qasm_string = "your_qasm_circuit_here"

# 2. Setup IBM Quantum Account (optional if credentials already configured)
# Will use saved credentials or environment variable if token not provided
setup_ibm_quantum_account.sync()

# Works in Jupyter notebooks
# 3. AI Clifford Synthesis

# 3.1 AI Routing [Optional]
routed_circuit = ai_routing.sync(circuit=qasm_string, backend_name="backend_name")
# Response contains QPY format (base64-encoded) for precision when chaining
routed_qpy_string = routed_circuit['circuit_qpy']
print(f"Routed circuit (QPY): {routed_qpy_string}")

# 3.2 AI Clifford Synthesis pass (use QPY for chaining)
clifford_synthesized_circuit = ai_clifford_synthesis.sync(
    circuit=routed_qpy_string,
    backend_name="backend_name",
    circuit_format="qpy"  # Specify QPY input format
)
print(f"Clifford synthesized circuit (QPY): {clifford_synthesized_circuit['circuit_qpy']}")

# 4. Convert QPY to human-readable QASM3 (optional)
from qiskit_mcp_server import qpy_to_qasm3
conversion = qpy_to_qasm3(clifford_synthesized_circuit['circuit_qpy'])
if conversion["status"] == "success":
    print(f"Human-readable circuit:\n{conversion['qasm3']}")

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 (QISKIT_IBM_TOKEN, OPENAI_API_KEY, etc.)
load_dotenv()

# Sample Clifford circuit
SAMPLE_CLIFFORD = """
OPENQASM 3.0;
include "stdgates.inc";
qubit[3] q;
h q[0];
cx q[0], q[1];
s q[2];
"""

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

    # Use persistent session for efficient tool calls
    async with mcp_client.session("qiskit-ibm-transpiler") 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"Synthesize this Clifford circuit for ibm_fez: {SAMPLE_CLIFFORD}")
        print(response)

asyncio.run(main())

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

其他测试和调试服务的方法

1. 在终端中进入克隆的仓库目录

2. 切换到虚拟环境

   source .venv/bin/activate
   

3. 运行 MCP Inspector：

   npx @modelcontextprotocol/inspector uv run qiskit-ibm-transpiler-mcp-server
   

4. 在浏览器中打开控制台消息中显示的 URL，例如：

   MCP Inspector is up and running at http://localhost:6277
   

注意：启动 MCP inspector 需要安装 node 和 npm

API 参考

工具

设置 IBM 账户

使用 API token 配置 IBM Quantum 账户。

setup_ibm_quantum_account_tool(token: Optional[str] = None, channel: str = "ibm_quantum_platform")

参数：

• token（可选）：IBM Quantum API token。如果未提供，函数将：
  1. 检查 QISKIT_IBM_TOKEN 环境变量
  2. 使用 ~/.qiskit/qiskit-ibm.json 中保存的凭据
• channel：服务频道（默认值："ibm_quantum_platform"）

返回： 设置状态和账户信息

注意： 如果已有保存的凭据，或已设置 QISKIT_IBM_TOKEN 环境变量，可以不带参数调用此函数，也可以完全跳过此步骤，直接使用其他函数。

AI 路由

对输入量子电路进行路由。它会在电路中插入 SWAP 操作，使双量子比特操作与给定的耦合映射兼容。耦合映射会限制可执行操作的量子比特对。建议在其他任何 AI 转译合成通道之前运行路由通道。

ai_routing(
   circuit: str,
   backend_name: str,
   optimization_level: int = 1,
   layout_mode: str = "optimize",
   optimization_preferences: Literal[
      "n_cnots", "n_gates", "cnot_layers", "layers", "noise"
      ] | list[Literal["n_cnots", "n_gates", "cnot_layers", "layers", "noise"]] | None = None,
   local_mode: bool = True,
   coupling_map: list[list[int]] | None = None,
   circuit_format: str = "qasm3"
)

参数：

• circuit：以 QASM 3.0 字符串或 base64 编码的 QPY 格式表示的量子电路
• backend_name：用于映射输入电路合成的 Qiskit Runtime Service 后端名称
• optimization_level（可选）：转译过程中要应用的优化级别。有效值为 [1,2,3]，其中 1 表示优化程度最低（速度最快），3 表示优化程度最高（耗时最长）
• layout_mode（可选）：指定如何处理布局选择。可取以下值：
  • "keep"：保留之前转译器通道设置的布局。通常用于必须在设备的特定量子比特上运行电路的情况。由于优化空间较小，结果通常较差
  • "improve"：适用于已有较好的布局初始猜测的情况
  • "optimize"：默认模式。适用于通常情况下布局猜测不佳或没有布局猜测的电路。此模式会忽略之前的布局选择
• optimization_preferences（可选）：指定优化时要减少的指标：CNOT 门数量（n_cnots）、门数量（n_gates）、CNOT 层数（cnot_layers）、层数（layers）和/或噪声（noise）
• local_mode（可选）：决定 AIRouting 通道的运行位置。若为 False，AIRouting 会通过 Qiskit Transpiler Service 远程运行。若为 True，软件包会尝试在本地环境运行该通道；如果找不到所需依赖项，则回退到云端模式
• coupling_map（可选）：表示后端拓扑的量子比特对列表。若提供，则会覆盖后端的耦合映射。适用于指定特定量子比特子集
• circuit_format（可选）：输入电路的格式（"qasm3" 或 "qpy"）。默认为 "qasm3"

返回值： 字典，包含：

• status："success" 或 "error"
• circuit_qpy：Base64 编码的 QPY 格式
• original_circuit：输入电路的指标（num_qubits、depth、size、two_qubit_gates）
• optimized_circuit：优化后电路的指标（num_qubits、depth、size、two_qubit_gates）
• improvements：计算得出的改进指标（depth_reduction、two_qubit_gate_reduction）

注意： 目前仅支持本地模式执行

混合式 AI 转译

使用混合式 PassManager 转译量子电路，将 Qiskit 的启发式优化与 AI 驱动的转译器 Pass 相结合。这可通过统一的流水线实现端到端转译。

hybrid_ai_transpile(
   circuit: str,
   backend_name: str,
   ai_optimization_level: int = 3,
   optimization_level: int = 3,
   ai_layout_mode: str = "optimize",
   initial_layout: list[int] | None = None,
   coupling_map: list[list[int]] | None = None,
   circuit_format: str = "qasm3"
)

参数：

• circuit：以 QASM 3.0 字符串或 base64 编码的 QPY 表示的量子电路
• backend_name：目标 IBM Quantum 后端（例如，'ibm_boston'、'ibm_fez'）
• ai_optimization_level（可选）：AI 组件的优化级别（1-3）。级别越高，效果越好，但需要更多计算资源
• optimization_level（可选）：PassManager 中启发式组件的优化级别（1-3）
• ai_layout_mode（可选）：指定 AI 路由组件如何处理布局选择：
  • "keep"：遵循先前转译器 Pass 设置的布局
  • "improve"：使用先前的布局作为优化起点
  • "optimize"：默认值；对于一般电路，忽略先前选择的布局。注意：如果提供了 initial_layout 且使用 'optimize'，则会自动转换为 'improve'，以利用用户提供的布局
• initial_layout（可选）：指定虚拟量子比特放置位置的物理量子比特索引列表。例如，[0, 1, 5, 6, 7] 会将虚拟量子比特 0 映射到物理量子比特 0，将虚拟量子比特 1 映射到物理量子比特 1，依此类推。
• coupling_map（可选）：表示后端拓扑结构的量子比特对列表。如果提供，则会覆盖后端的耦合图。适用于指定目标量子比特子集
• circuit_format（可选）：输入电路的格式（"qasm3" 或 "qpy"）。默认为 "qasm3"

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

• status："success" 或 "error"
• circuit_qpy：Base64 编码的 QPY 格式
• original_circuit：输入电路的指标（num_qubits、depth、size、two_qubit_gates）
• optimized_circuit：优化后电路的指标（num_qubits、depth、size、two_qubit_gates）
• improvements：计算得出的改进情况（depth_reduction、two_qubit_gate_reduction）

AI Clifford 综合

对 Clifford 电路（由 H、S 和 CX 门组成的代码块）进行综合。目前支持最多包含 9 个量子比特的代码块。

ai_clifford_synthesis(
   circuit: str,
   backend_name: str,
   replace_only_if_better: bool = True,
   local_mode: bool = True,
   circuit_format: str = "qasm3"
)

参数：

• circuit：以 QASM 3.0 字符串或 base64 编码的 QPY 表示的量子电路
• backend_name：用于映射输入电路综合结果的 Qiskit Runtime Service 后端名称
• replace_only_if_better（可选）：默认情况下，只有在综合后的子电路优于原始子电路时（目前仅检查 CNOT 数量），才会替换原始子电路；将其设为 False 可强制始终替换电路
• local_mode（可选）：确定 AI Clifford 综合的运行位置。如果为 False，则通过 Qiskit Transpiler Service 远程运行 AI Clifford 综合。如果为 True，该软件包会尝试在本地环境中运行此 Pass；如果找不到所需依赖项，则回退到云模式
• circuit_format（可选）：输入电路的格式（"qasm3" 或 "qpy"）。默认为 "qasm3"

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

• status："success" 或 "error"
• circuit_qpy：Base64 编码的 QPY 格式
• original_circuit：输入电路的指标（num_qubits、depth、size、two_qubit_gates）
• optimized_circuit：优化后电路的指标（num_qubits、depth、size、two_qubit_gates）
• improvements：计算得出的改进情况（depth_reduction、two_qubit_gate_reduction）

**注意：**目前仅支持本地模式运行

AI 线性函数综合

用于线性函数电路（由 CX 和 SWAP 门组成的模块）的综合。目前最多支持包含 9 个量子比特的模块。

ai_linear_function_synthesis(
   circuit: str,
   backend_name: str,
   replace_only_if_better: bool = True,
   local_mode: bool = True,
   circuit_format: str = "qasm3"
)

参数：

• circuit：以 QASM 3.0 字符串或 base64 编码的 QPY 表示的量子电路
• backend_name：用于映射输入电路综合的 Qiskit Runtime Service 后端名称
• replace_only_if_better（可选）：默认情况下，只有当综合后的子电路优于原始子电路时（目前仅检查 CNOT 数量），才会替换原始子电路；但可将 replace_only_if_better 设置为 False，强制始终替换电路
• local_mode（可选）：确定线性函数综合过程的运行位置。如果为 False，则通过 Qiskit Transpiler Service 远程运行线性函数综合。如果为 True，软件包会尝试在本地环境中运行该过程；如果未找到所需依赖项，则回退到云模式
• circuit_format（可选）：输入电路的格式（"qasm3" 或 "qpy"）。默认为 "qasm3"

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

• status："success" 或 "error"
• circuit_qpy：Base64 编码的 QPY 格式
• original_circuit：输入电路的指标（num_qubits、depth、size、two_qubit_gates）
• optimized_circuit：优化后电路的指标（num_qubits、depth、size、two_qubit_gates）
• improvements：计算得出的改进指标（depth_reduction、two_qubit_gate_reduction）

**注意：**目前仅支持在本地模式下执行

AI 置换综合

用于置换电路（由 SWAP 门组成的模块）的综合。目前支持包含 65、33 和 27 个量子比特的模块。

ai_permutation_synthesis(
   circuit: str,
   backend_name: str,
   replace_only_if_better: bool = True,
   local_mode: bool = True,
   circuit_format: str = "qasm3"
)

参数：

• circuit：以 QASM 3.0 字符串或 base64 编码的 QPY 表示的量子电路
• backend_name：用于映射输入电路综合的 Qiskit Runtime Service 后端名称
• replace_only_if_better（可选）：默认情况下，只有当综合后的子电路优于原始子电路时（目前仅检查 CNOT 数量），才会替换原始子电路；但可将 replace_only_if_better 设置为 False，强制始终替换电路
• local_mode（可选）：确定 AI 置换综合过程的运行位置。如果为 False，则通过 Qiskit Transpiler Service 远程运行 AI 置换综合。如果为 True，软件包会尝试在本地环境中运行该过程；如果未找到所需依赖项，则回退到云模式
• circuit_format（可选）：输入电路的格式（"qasm3" 或 "qpy"）。默认为 "qasm3"

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

• status："success" 或 "error"
• circuit_qpy：Base64 编码的 QPY 格式
• original_circuit：输入电路的指标（num_qubits、depth、size、two_qubit_gates）
• optimized_circuit：优化后电路的指标（num_qubits、depth、size、two_qubit_gates）
• improvements：计算得出的改进指标（depth_reduction、two_qubit_gate_reduction）

**注意：**目前仅支持在本地模式下执行

AI Pauli Network 综合

针对 Pauli Network 电路（由 H、S、SX、CX、RX、RY 和 RZ 门组成的模块）的综合。目前支持最多六量子比特的模块。

ai_pauli_network_synthesis(
   circuit: str,
   backend_name: str,
   replace_only_if_better: bool = True,
   local_mode: bool = True,
   circuit_format: str = "qasm3"
)

参数：

• circuit：以 QASM 3.0 字符串或 Base64 编码的 QPY 表示的量子电路
• backend_name：Qiskit Runtime Service 后端名称，用于映射输入电路综合
• replace_only_if_better（可选）：默认情况下，仅当合成后的子电路优于原子电路时（目前只检查 CNOT 数量），才会替换原子电路；将 replace_only_if_better=False 可强制始终替换电路
• local_mode（可选）：确定 AI Pauli Network 综合流程的运行位置。如果为 False，AI Pauli Network 综合将通过 Qiskit Transpiler Service 远程运行。如果为 True，程序包会尝试在本地环境中运行该流程；如果未找到所需依赖项，则回退到云模式
• circuit_format（可选）：输入电路的格式（"qasm3" 或 "qpy"）。默认为 "qasm3"

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

• status："success" 或 "error"
• circuit_qpy：Base64 编码的 QPY 格式
• original_circuit：输入电路的指标（num_qubits、depth、size、two_qubit_gates）
• optimized_circuit：优化后电路的指标（num_qubits、depth、size、two_qubit_gates）
• improvements：计算得出的改进指标（depth_reduction、two_qubit_gate_reduction）

**注意：**目前仅支持本地模式执行

测试

本项目包含全面的单元测试和集成测试。

运行测试

快速运行测试：

./run_tests.sh

手动运行测试命令：

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

# Run all tests
uv run pytest

# Run only unit tests
uv run pytest -m "not integration"

# Run only integration tests
uv run pytest -m "integration"

# Run tests with coverage
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/test_server.py -v

测试结构

• tests/integration/test_qta.py - 异步服务函数的集成测试
• tests/integration/test_sync.py - 同步服务函数的集成测试
• tests/integration/test_mcp_server.py - 通用集成测试
• tests/unit/test_qta.py - 异步服务函数的单元测试
• tests/unit/test_sync.py - 同步服务函数的单元测试
• tests/unit/test_utils.py - 工具函数的单元测试
• tests/unit/test_qiskit_runtime_service_provider.py - QiskitRuntimeServiceProvider Singleton 的单元测试
• tests/conftest.py - 测试夹具和配置
• tests/utils/helpers.py - 用于计算集成测试中 2 量子比特门数量和深度改进的辅助函数
• tests/qasm/ - /qasm 文件夹中的三个 QASM 3.0 测试用例（2 个有效，1 个格式错误）

测试覆盖范围

测试套件涵盖：

• ✅ 服务初始化和账户设置
• ✅ AI 综合流程（模拟和真实）
• ✅ 错误处理和验证
• ✅ 集成场景（模拟和真实）
• ✅ 工具处理程序

改进方向

• 集成 Collections，以实现完整的 AI 综合流程