Qiskit Gym MCP Server

Qiskit Gym MCP サーバー

qiskit-gym を使用して、強化学習ベースの量子回路合成機能を提供する Model Context Protocol（MCP）サーバーです。

機能

• RL モデルのトレーニング：強化学習エージェントをトレーニングして、最適な量子回路を合成します
• バックグラウンドトレーニング：ポーリングに対応したバックグラウンドスレッドで、長時間のトレーニングを実行します
• 3 種類の合成：
  • 置換：SWAP ゲートを最小限に抑えた量子ビットのルーティング
  • 線形関数：線形ブール関数の CNOT 合成
  • Clifford：カスタムゲートセットによる最適な Clifford 回路合成
• ハードウェア対応：IBM Heron、Nighthawk、および一般的なグリッド／線形トポロジーのプリセット
• IBM の正確なトポロジー：IBM Quantum のフェイクバックエンドから正確な結合マップを取得できます（オフラインで利用でき、認証情報は不要です）
• サブトポロジーの抽出：ハードウェア結合マップから連結サブグラフを抽出し、対象を絞ったトレーニングを行えます
• モデルの永続化：トレーニング済みモデルの保存、読み込み、管理
• TensorBoard との統合：TensorBoard でトレーニングの進捗を監視できます

インストール

pip install qiskit-gym-mcp-server

または、ソースからインストールします。

git clone https://github.com/Qiskit/mcp-servers
cd mcp-servers/qiskit-gym-mcp-server
pip install -e .

クイックスタート

Claude Desktop の設定

Claude Desktop の設定ファイル（~/Library/Application Support/Claude/claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "qiskit-gym": {
      "command": "qiskit-gym-mcp-server"
    }
  }
}

ワークフローの例

User: "Train a model to synthesize Clifford circuits on a 3x3 grid topology"

AI Agent:
1. create_clifford_env_tool(num_qubits=9, preset="grid_3x3")  # -> env_id
2. start_training_tool(env_id, algorithm="ppo", num_iterations=200)  # -> session_id, model_id
3. save_model_tool(session_id, model_name="clifford_3x3_v1")  # -> saved to disk

User: "Train on all 6-qubit subtopologies from IBM Nighthawk"

AI Agent:
1. extract_subtopologies_tool(preset="ibm_nighthawk", num_qubits=6)  # -> list of subtopologies
2. For each subtopology:
   - create_clifford_env_tool(num_qubits=6, coupling_map=subtopology["edges"])
   - start_training_tool(env_id, algorithm="ppo", num_iterations=100)
   - save_model_tool(session_id, model_name=f"nighthawk_6q_{i}")

User: "Train a model using the exact topology of IBM Fez backend"

AI Agent:
1. get_fake_backend_coupling_map_tool(backend_name="fake_fez")  # -> exact 156-qubit Heron topology
2. extract_subtopologies_tool(edges=coupling_map["edges"], num_qubits=5)  # -> 5-qubit subtopologies
3. For each subtopology:
   - create_permutation_env_tool(num_qubits=5, coupling_map=subtopology["edges"])
   - start_training_tool(env_id, algorithm="ppo", num_iterations=100)

User: "Train a model in the background so I can do other things"

AI Agent:
1. create_clifford_env_tool(num_qubits=6, preset="grid_2x3")  # -> env_id
2. start_training_tool(env_id, algorithm="ppo", num_iterations=500, background=True)  # -> session_id (returns immediately)
3. (User can now ask other questions or the agent can do other work)
4. get_training_status_tool(session_id)  # -> check progress
5. wait_for_training_tool(session_id, timeout=600)  # -> blocks until complete, returns model_id
6. save_model_tool(session_id, model_name="clifford_6q_v1")

ツールリファレンス

環境管理

ツール	説明
create_permutation_env_tool	SWAP ルーティング用の PermutationGym を作成
create_linear_function_env_tool	CNOT 合成用の LinearFunctionGym を作成
create_clifford_env_tool	カスタムゲートセットで CliffordGym を作成
list_environments_tool	アクティブな環境を一覧表示
get_environment_info_tool	環境の詳細を取得
delete_environment_tool	環境を削除

トレーニング

ツール	説明
start_training_tool	RL トレーニング（PPO または AlphaZero）を開始します。background=True に対応
wait_for_training_tool	バックグラウンドトレーニングの完了を待機
batch_train_environments_tool	複数の環境をトレーニング
get_training_status_tool	トレーニングの進捗とメトリクスを取得
stop_training_tool	トレーニングセッションを停止
list_training_sessions_tool	すべてのトレーニングセッションを一覧表示

合成

ツール	説明
synthesize_permutation_tool	最適な SWAP 回路を生成
synthesize_linear_function_tool	最適な CNOT 回路を生成
synthesize_clifford_tool	最適な Clifford 回路を生成

モデル管理

ツール	説明
save_model_tool	トレーニング済みモデルをディスクに保存
load_model_tool	ディスクからモデルを読み込み
list_saved_models_tool	ディスク上のモデルを一覧表示
list_loaded_models_tool	メモリ内のモデルを一覧表示
delete_model_tool	モデルを削除
get_model_info_tool	モデルの詳細を取得

結合マップ

ツール	説明
create_coupling_map_tool	カスタム結合マップを作成
extract_subtopologies_tool	ハードウェアから N 量子ビットのサブトポロジーを抽出
list_subtopology_shapes_tool	サブトポロジーの形状（ライン、グリッドなど）を一覧表示
get_fake_backend_coupling_map_tool	フェイク IBM バックエンドから正確なトポロジーを取得（認証情報は不要）
list_available_fake_backends_tool	オフラインでのトポロジー取得に利用できるすべてのフェイクバックエンドを一覧表示

ユーティリティツール

ツール	説明
generate_random_permutation_tool	テスト用のランダムな置換を生成します
generate_random_linear_function_tool	テスト用のランダムな線形関数を生成します
generate_random_clifford_tool	テスト用のランダムなクリフォード要素を生成します
convert_qpy_to_qasm3_tool	QPY 回路を人間が読みやすい QASM3 に変換します
convert_qasm3_to_qpy_tool	QASM3 回路を QPY 形式に変換します

ハードウェアプリセット

プリセット	量子ビット数	トポロジー	説明
ibm_heron_r1	133	Heavy-hex	IBM Heron r1 プロセッサ
ibm_heron_r2	156	Heavy-hex	IBM Heron r2 プロセッサ
ibm_nighthawk	120	10x12 grid	IBM Nighthawk（Heron と比べて深さが 600% 向上）
grid_3x3	9	Grid	3x3 の正方形グリッド
grid_5x5	25	Grid	5x5 の正方形グリッド
linear_5	5	Line	5 量子ビットの線形チェーン
linear_10	10	Line	10 量子ビットの線形チェーン

リソース

URI	説明
qiskit-gym://workflows	まずはこちら - ステップごとのワークフローとクイックスタートガイド
qiskit-gym://presets/coupling-maps	利用可能なハードウェアプリセット
qiskit-gym://algorithms	PPO、AlphaZero のドキュメント
qiskit-gym://policies	BasicPolicy、Conv1dPolicy のドキュメント
qiskit-gym://environments	環境タイプのドキュメント
qiskit-gym://training/sessions	アクティブなトレーニングセッション
qiskit-gym://models	読み込み済みのモデル
qiskit-gym://server/config	サーバー設定

設定

環境変数：

# Model storage directory (default: ~/.qiskit-gym/models)
QISKIT_GYM_MODEL_DIR=~/.qiskit-gym/models

# TensorBoard logs (default: ~/.qiskit-gym/runs)
QISKIT_GYM_TENSORBOARD_DIR=~/.qiskit-gym/runs

# Training limits (0 = no limit, default)
# QISKIT_GYM_MAX_ITERATIONS=10000  # Uncomment to set a limit
QISKIT_GYM_MAX_QUBITS=15
QISKIT_GYM_MAX_SEARCHES=10000

開発

# Install with dev dependencies
pip install -e ".[all]"

# Run tests
./run_tests.sh

# Or manually
uv run pytest tests/ -v
uv run ruff check src tests
uv run mypy src

依存関係

• qiskit-gym - 量子回路合成用の強化学習環境
• FastMCP - MCP サーバーフレームワーク
• Qiskit - 量子コンピューティングフレームワーク
• qiskit-ibm-runtime - IBM Quantum アクセスおよびフェイクバックエンド

ライセンス

Apache 2.0 - 詳細は LICENSE を参照してください。

貢献

貢献のガイドラインについては、CONTRIBUTING.md を参照してください。