Qiskit MCP Server

Qiskit MCP Server

Qiskit のパスマネージャーを使用して量子回路のトランスパイル機能を提供する Model Context Protocol（MCP）サーバーです。このサーバーにより、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 ノートブックを含む詳しい使用例については、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 のプリセットパスマネージャーを使用して量子回路をトランスパイルします。

パラメーター：

• 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 も受け付けます。

戻り値： 元の回路とトランスパイル後の回路の情報、および最適化指標を含む辞書

注： レベル 3 の最適化は、20 量子ビット超または 500 ゲート超の回路では非常に低速になる場合があります。品質を保ちつつ高速に処理するには、レベル 2 を使用してください。

analyze_circuit(circuit, circuit_format="qasm3")

回路の構造と複雑さを分析します。

戻り値： ゲート数、深さ、および分類（単一／2 量子ビット／複数量子ビットゲート）を含む辞書

compare_optimization_levels(circuit, circuit_format="qasm3")

すべての最適化レベルにおけるトランスパイル結果を比較します。

戻り値： レベル 0～3 の深さ、サイズ、ゲートを比較する辞書

回路形式のサポート

このサーバーは入力に次の 2 つの回路形式をサポートしています。

形式	説明
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	2D グリッド接続
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 を使用してください（品質と速度のバランスが最適です）。
• レベル 3 は、回路の品質が重要で、かつ回路が小規模（<20 qubits、<500 gates）な場合にのみ使用してください。
• 迅速なプロトタイピングや開発には、レベル 0 または 1 を使用してください。
• compare_optimization_levels ツールを使うと、特定の回路に最適なレベルを特定できます。

トランスパイルのステージ

Qiskit トランスパイラーは、回路を次の 6 つのステージで処理します。

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ファイルをご覧ください。