Qiskit IBM Transpiler MCP Server

qiskit-ibm-transpiler-mcp-server

Qiskit トランスパイラー用の MCP サーバーです。入出力ツール形式として QASM 3.0 を使用し、AI ルーティング、 AI Clifford 合成、AI Linear Function 合成、AI Permutation 合成、AI Pauli Network 合成に対応しています。

特長

• AI トランスパイラー：ルーティングパスと合成パスの両方で、機械学習ベースの最適化を実行します
• QPY 出力：ツールやサーバーを連携させる際の精度を保つため、base64 エンコードされた QPY 形式を返します
• 2 種類の入力形式：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 ノートブックを含む詳細な例については、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 and npm が必要です

API リファレンス

ツール

IBM アカウントのセットアップ

IBM Quantum アカウントを API トークンで設定します。

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

パラメーター：

• token（省略可）：IBM Quantum API トークン。指定されていない場合、関数は次の処理を行います：
  1. QISKIT_IBM_TOKEN 環境変数を確認します
  2. ~/.qiskit/qiskit-ibm.json の保存済み認証情報を使用します
• channel：サービスチャネル（デフォルト："ibm_quantum_platform"）

戻り値： セットアップの状態とアカウント情報

注： 認証情報がすでに保存されている場合、または QISKIT_IBM_TOKEN 環境変数が設定されている場合、この関数はパラメーターなしで呼び出すか、呼び出しを省略して他の関数を直接使用できます。

AI Routing

入力された量子回路をルーティングします。回路に SWAP 操作を挿入し、適用可能な操作の量子ビットのペアを制限する指定の結合マップに対して、2 量子ビット操作が適合するようにします。他の 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）のうち、1 つ以上を指定します。
• 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 トランスパイル

Qiskit のヒューリスティック最適化と、AI を活用したトランスパイラーパスを組み合わせたハイブリッドパスマネージャーを使用して、量子回路をトランスパイルします。これにより、エンドツーエンドのトランスパイルを単一の統合パイプラインで実行できます。

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"：以前のトランスパイラーパスで設定されたレイアウトを維持します
  • "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 数のみを確認します）。ただし、replace_only_if_better=False を設定すると、常に回路を置き換えるようにできます
• local_mode（任意）：AI Clifford 合成の実行場所を指定します。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 Linear Function 合成

Linear Function 回路（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（任意）：Linear Function 合成パスの実行場所を指定します。False の場合、Linear Function 合成は 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 Permutation 合成

Permutation 回路（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 Permutation 合成パスの実行場所を指定します。False の場合、AI Permutation 合成は 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 Pauli Network 合成

Pauli Network 回路（H、S、SX、CX、RX、RY、RZ ゲートのブロック）の合成です。現在は、最大 6 量子ビットのブロックに対応しています。

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 - utils 関数のユニットテスト
• tests/unit/test_qiskit_runtime_service_provider.py - QiskitRuntimeServiceProvider Singleton のユニットテスト
• tests/conftest.py - テストフィクスチャと設定
• tests/utils/helpers.py - 統合テストで 2 量子ビットゲート数と深さの改善を計算するヘルパー関数
• tests/qasm/ - /qasm フォルダー内の 3 つの QASM 3.0 テストケース（有効なもの 2 件、不正なもの 1 件）

テストカバレッジ

テストスイートでは、次の項目を網羅しています。

• ✅ サービスの初期化とアカウントの設定
• ✅ AI 合成パス（モックおよび実際の実行）
• ✅ エラー処理と検証
• ✅ 統合シナリオ（モックおよび実際の実行）
• ✅ ツールハンドラー

改善点

• 完全な AI 合成パスを実現するため、Collections を統合する