Qiskit IBM Runtime MCP Server

Qiskit IBM Runtime MCP 服务

一个功能全面的模型上下文协议（MCP）服务，通过 Qiskit IBM Runtime 为 AI 助手提供 IBM Quantum 计算服务的访问能力。此服务可直接在 AI 对话中创建、执行和管理量子电路。

功能

• 使用原语执行电路：使用 EstimatorV2（期望值）和 SamplerV2（测量采样）运行电路，并内置错误缓解功能
• 量子后端管理：列出、检查量子后端并获取其校准数据
• 量子比特优化：根据实时校准数据查找最佳量子比特链和子图
• 作业管理：监控、取消作业并获取作业结果
• 账户管理：轻松设置和配置 IBM Quantum 账户

先决条件

• Python 3.10 或更高版本
• IBM Quantum 账户（可在 quantum.cloud.ibm.com 免费注册）
• IBM Quantum API 令牌

安装

从 PyPI 安装

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

pip install qiskit-ibm-runtime-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
   

2. 获取 IBM Quantum 令牌（如果尚未保存凭据）：

   • 访问 IBM Quantum
   • 找到你的 API 密钥。在 控制面板 中创建 API 密钥，然后将其复制到安全位置，以便用于身份验证。了解更多信息

3. 配置凭据（选择一种方式）：

   选项 A：环境变量（推荐）

   # Copy the example environment file
   cp .env.example .env
   
   # Edit .env and add your IBM Quantum API token
   export QISKIT_IBM_TOKEN="your_token_here"
   
   # Optional: Set instance for faster startup (skips instance lookup)
   export QISKIT_IBM_RUNTIME_MCP_INSTANCE="your-instance-crn"
   

   选项 B：在本地保存凭据

   from qiskit_ibm_runtime import QiskitRuntimeService
   
   # Save your credentials (one-time setup)
   QiskitRuntimeService.save_account(
       channel="ibm_quantum_platform",
       token="your_token_here",
       overwrite=True
   )
   

   这会将凭据保存到 ~/.qiskit/qiskit-ibm.json

   选项 C：直接传递令牌

   # Provide token when setting up the account
   await setup_ibm_quantum_account_tool(token="your_token_here")
   

   凭据解析优先级： 服务会按以下顺序查找凭据：

   1. 传递给 setup_ibm_quantum_account_tool() 的显式令牌
   2. QISKIT_IBM_TOKEN 环境变量
   3. 保存在 ~/.qiskit/qiskit-ibm.json 中的凭据

   实例配置（可选）： 若要加快服务初始化速度，可以指定 IBM Quantum 实例：

   • 将实例 CRN 设置为 QISKIT_IBM_RUNTIME_MCP_INSTANCE 环境变量的值
   • 这样可跳过可能较慢的自动实例查找
   • 在 IBM Quantum Platform 中查找实例 CRN

   实例优先级：

   • 如果保存的凭据中包含实例（通过 save_account(instance="...")），SDK 会自动使用该实例
   • QISKIT_IBM_RUNTIME_MCP_INSTANCE 会覆盖凭据中保存的任何实例
   • 如果两者均未设置，SDK 会在所有实例中执行较慢的查找

   注意： QISKIT_IBM_RUNTIME_MCP_INSTANCE 是特定于 MCP 服务的变量，并非标准的 Qiskit SDK 环境变量。

快速开始

运行服务

uv run qiskit-ibm-runtime-mcp-server

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

基本用法示例

异步用法（库）

# 1. Setup IBM Quantum Account (optional if credentials already configured)
# Will use saved credentials or environment variable if token not provided
await setup_ibm_quantum_account()  # Uses saved credentials/env var
# OR
await setup_ibm_quantum_account(token="your_token_here")  # Explicit token

# 2. List Available Backends (no setup needed if credentials are saved)
backends = await list_backends()
print(f"Available backends: {len(backends['backends'])}")

# 3. Get the least busy backend
backend = await least_busy_backend()
print(f"Least busy backend: {backend}")

# 4. Get backend's properties
backend_props = await get_backend_properties("backend_name")
print(f"Backend_name properties: {backend_props}")

# 5. List recent jobs
jobs = await list_my_jobs(10)
print(f"Last 10 jobs: {jobs}")

# 6. Get job status
job_status = await get_job_status("job_id")
print(f"Job status: {job_status}")

# 7. Get job results (when job is DONE)
results = await get_job_results("job_id")
print(f"Counts: {results['counts']}")

# 8. Cancel job
cancelled_job = await cancel_job("job_id")
print(f"Cancelled job: {cancelled_job}")

同步用法（脚本、Jupyter）

对于不支持异步操作的框架，所有异步函数都有一个 .sync 属性：

from qiskit_ibm_runtime_mcp_server.ibm_runtime import (
    setup_ibm_quantum_account,
    list_backends,
    least_busy_backend,
    get_backend_properties,
    get_backend_calibration,
    get_coupling_map,
    find_optimal_qubit_chains,
    find_optimal_qv_qubits,
    run_estimator,
    run_sampler,
    list_my_jobs,
    get_job_status,
    get_job_results,
    cancel_job
)

# Optional: Setup account if not already configured
# Will automatically use QISKIT_IBM_TOKEN env var or saved credentials
setup_ibm_quantum_account.sync()  # No token needed if already configured

# Use .sync for synchronous execution - no setup needed if credentials saved
backends = list_backends.sync()
print(f"Available backends: {backends['total_backends']}")

# Get least busy backend
backend = least_busy_backend.sync()
print(f"Least busy: {backend['backend_name']}")

# Find optimal qubit chains for linear experiments
chains = find_optimal_qubit_chains.sync(backend['backend_name'], chain_length=5)
print(f"Best chain: {chains['chains'][0]['qubits']}")

# Find optimal qubits for Quantum Volume experiments
qv_qubits = find_optimal_qv_qubits.sync(backend['backend_name'], num_qubits=5)
print(f"Best QV subgraph: {qv_qubits['subgraphs'][0]['qubits']}")

# Works in Jupyter notebooks (handles nested event loops automatically)
jobs = list_my_jobs.sync(limit=5)
print(f"Recent jobs: {len(jobs['jobs'])}")

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()

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

    # Use persistent session for efficient tool calls
    async with mcp_client.session("qiskit-ibm-runtime") 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("What QPUs are available and which one is least busy?")
        print(response)

asyncio.run(main())

如需了解更多大模型提供商（Anthropic、Google、Ollama、Watsonx）以及包含 Jupyter 笔记本的详细示例，请参阅 examples/ 目录。

API 参考

工具

这些是 MCP 客户端在 tools/list 中看到的名称。Host 可以为它们添加前缀（例如 mcp__<server>__<tool>），因此在编写允许列表或权限规则之前，请确认客户端如何显示名称。qiskit_ibm_runtime_mcp_server.ibm_runtime 中的 Python 函数（参见同步用法）名称相同，只是不带 _tool 后缀。

setup_ibm_quantum_account_tool(token: str = "", channel: str = "ibm_quantum_platform")

使用 API 令牌配置 IBM Quantum 账户。

参数：

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

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

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

list_backends_tool()

获取可用量子后端列表。

**返回：**后端信息数组，包括：

• 名称、状态、队列长度
• 量子比特数量、耦合图
• 模拟器或硬件的标识

least_busy_backend_tool()

获取当前可用且最空闲的 IBM Quantum 后端。

**返回：**待处理作业数量最少的后端

get_backend_properties_tool(backend_name: str)

获取指定后端的详细属性。

**返回：**完整的后端配置，包括：

• 硬件规格
• 门集和耦合图
• 当前运行状态
• 队列信息

get_coupling_map_tool(backend_name: str)

获取后端的耦合图（量子比特连通性）及详细分析。

支持真实后端（需要凭据）和模拟后端（无需凭据）。 离线测试时使用 fake_ 前缀（例如 fake_sherbrooke、fake_brisbane）。

参数：

• backend_name：后端名称（例如 ibm_brisbane 或 fake_sherbrooke）

**返回：**连通性信息，包括：

• edges：控制量子比特与目标量子比特连接对的列表
• adjacency_list：每个量子比特的邻居映射
• bidirectional：所有连接是否都能双向工作
• num_qubits：量子比特总数

使用场景：

• 电路优化和量子比特映射
• SWAP 门最小化规划
• 使用模拟后端进行离线测试

get_backend_calibration_tool(backend_name: str, qubit_indices: list[int] | None = None)

获取后端的校准数据，包括 T1、T2 相干时间和错误率。

参数：

• backend_name：后端名称（例如 ibm_brisbane）
• qubit_indices（可选）：特定量子比特索引列表。如果未提供，则返回前 10 个量子比特的数据。

**返回：**校准数据，包括：

• T1 和 T2 相干时间（以微秒为单位）
• 量子比特频率（以 GHz 为单位）
• 每个量子比特的读出错误率
• 常用门（x、sx、cx 等）的错误率
• faulty_qubits：不可运行的量子比特索引列表
• faulty_gates：不可运行的门及其受影响量子比特的列表
• 上次校准时间戳

**注意：**静态后端信息（processor_type、backend_version、quantum_volume）请使用 get_backend_properties_tool 获取。

find_optimal_qubit_chains_tool(backend_name, chain_length, num_results, metric)

根据连通性和校准数据，为量子实验寻找最优的线性量子比特链。

该工具通过结合耦合映射的连通性与实时校准数据，以算法方式识别最优量子比特链。适用于需要线性量子比特排列的实验。

参数：

• backend_name：后端名称（例如，ibm_brisbane）
• chain_length：链中的量子比特数（默认值：5，范围：2-20）
• num_results：返回的排名靠前的链数量（默认值：5，最大值：20）
• metric：要优化的评分指标：
  • two_qubit_error：最小化 CX/ECR 门错误之和（默认值）
  • readout_error：最小化测量错误之和
  • combined：对门错误、读出错误和相干性进行加权组合

**返回：**按排名排列的链及其详细指标：

• qubits：链中量子比特索引的有序列表
• score：总分（越低越好）
• qubit_details：每个量子比特的 T1、T2、readout_error
• edge_errors：每条连接的双量子比特门错误

使用场景：

• 为变分量子算法（VQE、QAOA）选择量子比特
• 为纠错实验规划线性量子比特布局
• 找出用于态传输的高保真度量子比特路径
• 优化用于一维物理模拟的量子比特选择

find_optimal_qv_qubits_tool(backend_name, num_qubits, num_results, metric)

为 Quantum Volume 实验寻找最优量子比特子图。

与线性链不同，Quantum Volume 适合采用密集连接的量子比特集合，使量子比特之间能够以尽可能少的 SWAP 操作进行交互。该工具会寻找连通子图，并根据连通性和校准质量对其排序。

参数：

• backend_name：后端名称（例如，ibm_brisbane）
• num_qubits：子图中的量子比特数（默认值：5，范围：2-10）
• num_results：返回的排名靠前的子图数量（默认值：5，最大值：20）
• metric：要优化的评分指标：
  • qv_optimized：针对 QV 的均衡评分（连通性 + 错误 + 相干性）（默认值）
  • connectivity：最大化内部边数并最小化路径长度
  • gate_error：最小化内部边上的双量子比特门错误总和

**返回：**按排名排列的子图及其详细指标：

• qubits：子图中的量子比特索引列表（已排序）
• score：总分（越低越好）
• internal_edges：子图内部的边数
• connectivity_ratio：internal_edges / max_possible_edges
• average_path_length：量子比特对之间的平均最短路径长度
• qubit_details：每个量子比特的 T1、T2、readout_error
• edge_errors：每条内部边的双量子比特门错误

使用场景：

• 为 Quantum Volume 实验选择最优量子比特
• 为随机线路采样寻找高密度连接区域
• 为变分算法找出高质量的量子比特簇
• 为需要全连接的算法规划量子比特分配

list_my_jobs_tool(limit: int = 10)

获取账户中的近期任务列表。

参数：

• limit：要获取的任务数量 N

get_job_status_tool(job_id: str)

检查已提交任务的状态。

参数：

• job_id：要查询状态的任务 ID

**返回：**当前任务状态、创建日期、后端信息

任务状态值：

• INITIALIZING：正在准备任务
• QUEUED：任务正在队列中等待
• RUNNING：任务正在执行
• DONE：任务已成功完成
• CANCELLED：任务已取消
• ERROR：任务发生错误，执行失败

get_job_results_tool(job_id: str)

从已完成的量子作业中获取测量结果。

参数：

• job_id：已完成作业的 ID

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

• status："success"、"pending" 或 "error"
• job_id：作业 ID
• job_status：作业当前状态
• counts：测量结果及其计数的字典（例如，{"00": 2048, "11": 2048}）
• shots：执行的总测量次数
• backend：所用后端的名称
• execution_time：量子执行时间（秒，如有）
• message：状态消息

工作流示例：

# 1. Submit job
result = await run_sampler_tool(circuit, backend_name)
job_id = result["job_id"]

# 2. Check status (poll until DONE)
status = await get_job_status_tool(job_id)
print(f"Status: {status['job_status']}")

# 3. When DONE, retrieve results
if status['job_status'] == 'DONE':
    results = await get_job_results_tool(job_id)
    print(f"Counts: {results['counts']}")

cancel_job_tool(job_id: str)

取消正在运行或排队中的作业。

参数：

• job_id：要取消的作业 ID

run_estimator_tool(circuit, observables, ...)

使用 Qiskit Runtime EstimatorV2 原语运行量子电路。计算可观测量的期望值，并内置错误缓解功能。

参数：

• circuit：量子电路（OpenQASM 3.0/2.0 字符串或 base64 编码的 QPY）
• observables：要测量的可观测量。支持：
  • 单个 Pauli 字符串："ZZ"
  • Pauli 字符串列表：["IIXY", "ZZII"]
  • 带权重的哈密顿量：[("XX", 0.5), ("ZZ", -0.3)]
• parameter_values（可选）：参数化电路的参数值
• backend_name（可选）：后端名称。如果未提供，则使用负载最低的后端。
• circuit_format："auto"（默认）、"qasm3" 或 "qpy"
• optimization_level：转译级别 0-3（默认：1）
• resilience_level：错误缓解级别 0-2（默认：1）
• zne_mitigation：启用零噪声外推（默认：True）
• zne_noise_factors（可选）：ZNE 的噪声因子（默认：(1, 1.5, 2)）

返回： 作业提交状态，包括 job_id、backend 和 error_mitigation 摘要。

注意： 作业以异步方式运行。使用 get_job_status_tool 监控作业，并使用 get_job_results_tool 获取期望值。

run_sampler_tool(circuit, ...)

使用 Qiskit Runtime SamplerV2 原语运行量子电路。返回测量结果样本，并内置错误缓解功能。

参数：

• circuit：量子电路（OpenQASM 3.0/2.0 字符串或 base64 编码的 QPY）。必须包含测量操作。
• backend_name（可选）：后端名称。如果未提供，则使用负载最低的后端。
• shots：测量重复次数（默认：4096）
• circuit_format："auto"（默认）、"qasm3" 或 "qpy"
• dynamical_decoupling：在空闲期间抑制退相干（默认：True）
• dd_sequence：DD 脉冲序列："XX"、"XpXm" 或 "XY4"（默认）
• twirling：对双量子比特门应用 Pauli Twirling（默认：True）
• measure_twirling：应用测量 Twirling 以缓解读出错误（默认：True）

返回： 作业提交状态，包括 job_id、backend、shots 和 error_mitigation 摘要。

注意： 作业以异步方式运行。使用 get_job_status_tool 监控作业，并使用 get_job_results_tool 获取测量计数。

list_saved_accounts_tool()

列出磁盘上保存的所有 IBM Quantum 账户。

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

• status："success" 或 "error"
• accounts：已保存账户的字典（以账户名称为键）
• 每个账户包含：channel、url、token（出于安全考虑已遮盖）
• message：状态消息

注意： 响应中的令牌会被遮盖，仅显示最后 4 个字符。

delete_saved_account_tool(account_name: str)

从磁盘删除已保存的 IBM Quantum 账户。

警告： 此操作会永久删除 ~/.qiskit/qiskit-ibm.json 中的凭据，且无法撤销。

参数：

• account_name：要删除的已保存账户名称。使用 list_saved_accounts_tool() 查找可用名称。

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

• status："success" 或 "error"
• deleted：布尔值，表示是否成功删除
• message：状态消息

active_account_info_tool()

获取当前活跃 IBM Quantum 账户的信息。

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

• status：“success”或“error”
• account_info：账户详情，包括 channel、url、token（已脱敏，以确保安全）

**注意：**响应中的令牌会经过脱敏处理，仅显示最后 4 个字符。

active_instance_info_tool()

获取当前活跃实例的云资源名称（CRN）。

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

• status：“success”或“error”
• instance_crn：用于标识活跃实例的 CRN 字符串

available_instances_tool()

列出当前活跃账户可用的所有 IBM Quantum 实例。

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

• status：“success”或“error”
• instances：可用实例列表，包含 CRN、计划、名称和定价信息
• total_instances：可用实例的数量

usage_info_tool()

获取当前活跃实例的使用统计信息和配额信息。

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

• status：“success”或“error”
• usage：使用指标，包括：
  • usage_consumed_seconds：本周期已消耗的时间
  • usage_limit_seconds：本周期的总配额
  • usage_remaining_seconds：剩余配额
  • usage_limit_reached：表示是否已达到上限的布尔值
  • usage_period：当前计费周期

资源

ibm://status

获取当前 IBM Quantum 服务状态和连接信息。

circuits://bell-state

预构建的 2 量子比特 Bell 态电路，生成 |Phi+> = (|00> + |11>)/sqrt(2)。将返回的 circuit 字段直接传递给 run_sampler_tool。预期结果：约 50% 为 '00'，约 50% 为 '11'。

circuits://ghz-state

预构建的 3 量子比特 GHZ 态电路，生成 (|000> + |111>)/sqrt(2)。预期结果：约 50% 为 '000'，约 50% 为 '111'。

circuits://random

预构建的 4 量子比特量子随机数生成器。每个量子比特都置于叠加态并进行测量。预期结果：全部 16 种结果的概率均约为 6.25%。

circuits://superposition

最简单的量子电路：对单个量子比特施加 Hadamard 门，生成 (|0> + |1>)/sqrt(2)。预期结果：约 50% 为 '0'，约 50% 为 '1'。

安全注意事项

• 安全存储 IBM Quantum 令牌：切勿将令牌提交到版本控制系统
• 在生产部署中使用环境变量：设置 QISKIT_IBM_TOKEN 环境变量
• 凭据优先级：服务端会按以下顺序自动解析凭据：
  1. 显式令牌参数（优先级最高）
  2. QISKIT_IBM_TOKEN 环境变量
  3. ~/.qiskit/qiskit-ibm.json 中保存的凭据（优先级最低）
• 令牌验证：服务端会拒绝 <PASSWORD>、<TOKEN> 等占位值，以防凭据意外损坏
• 在生产环境中实施速率限制：监控 API 请求频率
• 监控量子资源消耗：跟踪作业提交和后端使用情况

贡献

欢迎贡献！可改进的领域包括：

• 更多错误缓解／纠正技术
• 其他 qiskit-ibm-runtime 功能

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

注意：启动 MCP 检查器需要安装 node and npm

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

2. 切换到虚拟环境

   source .venv/bin/activate
   

3. 运行 MCP 检查器：

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

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

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

测试

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

运行测试

快速运行测试：

./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/test_server.py - 服务函数的单元测试
• tests/test_sync.py - 同步执行的单元测试
• tests/test_integration.py - 集成测试
• tests/conftest.py - 测试夹具和配置

测试覆盖范围

测试套件涵盖：

• ✅ 服务初始化和账户设置
• ✅ 后端列表、校准和分析
• ✅ 使用 EstimatorV2 和 SamplerV2 原语执行电路
• ✅ 作业管理和监控
• ✅ 同步执行（.sync 方法）
• ✅ 错误处理和输入验证
• ✅ 集成场景
• ✅ 资源和工具处理程序