Qiskit Gym MCP Server

io.github.Qiskit由 GitHub 帳號 Qiskit 發布v0.4.2更新於 Oct 24, 2026

MCP server for qiskit-gym reinforcement learning quantum circuit synthesis

已驗證STDIO僅桌面開發者工具AI 與機器學習

概覽

AI 產生的概覽

本機 MCP 伺服器，讓助理用 qiskit-gym 訓練強化學習代理並合成量子電路。

可以做什麼
  • 建立、檢視與刪除用於置換、線性函數與 Clifford 合成的強化學習環境
  • 啟動、批次訓練、查詢進度、等待與停止 PPO 或 AlphaZero 訓練工作階段，支援背景執行
  • 以已訓練模型合成最佳 SWAP、CNOT 與 Clifford 電路
  • 儲存、載入、列出、檢視與刪除磁碟或記憶體中的模型
  • 建立耦合圖、擷取 N 量子位元子拓撲，並從離線 IBM 模擬後端取得精確拓撲
  • 產生隨機測試輸入，並在 QPY 與 QASM3 之間轉換電路
適用情境
適合量子計算研究或實驗：需要助理架設 qiskit-gym 環境、執行訓練工作，並在網格、線性或 IBM 硬體拓撲上產生用於路由、CNOT 或 Clifford 合成的最佳化電路。
執行需求
以 Python 套件（qiskit-gym-mcp-server，可用 uvx 或 pip 安裝）透過 stdio 在本機執行，面向桌面用戶端。不需要任何憑證，包含取得 IBM 模擬後端拓撲。選用環境變數可設定模型與 TensorBoard 目錄及 QISKIT_GYM_MAX_QUBITS 等訓練上限。
安裝前請注意
訓練運算量大且可能耗時較久；背景工作階段以及 QISKIT_GYM_MAX_ITERATIONS、QISKIT_GYM_MAX_QUBITS 等上限可控制開銷。工具會寫入磁碟：模型存於 QISKIT_GYM_MODEL_DIR，日誌存於 QISKIT_GYM_TENSORBOARD_DIR，刪除類工具會移除環境與模型。未宣告任何身分驗證。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Qiskit Gym MCP Server，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Qiskit Gym MCP Server

[MCP Registry]

A Model Context Protocol (MCP) server that provides reinforcement learning-based quantum circuit synthesis capabilities using qiskit-gym.

Features

  • Train RL Models: Train reinforcement learning agents to synthesize optimal quantum circuits
  • Background Training: Run long training sessions in background threads with polling support
  • Three Synthesis Types:
    • Permutation: Qubit routing with minimal SWAP gates
    • Linear Function: CNOT synthesis for linear Boolean functions
    • Clifford: Optimal Clifford circuit synthesis with custom gate sets
  • Hardware Support: Presets for IBM Heron, Nighthawk, and common grid/linear topologies
  • Exact IBM Topologies: Access exact coupling maps from IBM Quantum fake backends (offline, no credentials needed)
  • Subtopology Extraction: Extract connected subgraphs from hardware coupling maps for targeted training
  • Model Persistence: Save, load, and manage trained models
  • TensorBoard Integration: Monitor training progress with TensorBoard

Installation

bash
pip install qiskit-gym-mcp-server

Or install from source:

bash
git clone https://github.com/Qiskit/mcp-serverscd mcp-servers/qiskit-gym-mcp-serverpip install -e .

Quick Start

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

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

Example Workflow

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_id2. start_training_tool(env_id, algorithm="ppo", num_iterations=200)  # -> session_id, model_id3. 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 subtopologies2. 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 topology2. extract_subtopologies_tool(edges=coupling_map["edges"], num_qubits=5)  # -> 5-qubit subtopologies3. 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_id2. 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 progress5. wait_for_training_tool(session_id, timeout=600)  # -> blocks until complete, returns model_id6. save_model_tool(session_id, model_name="clifford_6q_v1")

Tools Reference

Environment Management

ToolDescription
create_permutation_env_toolCreate PermutationGym for SWAP routing
create_linear_function_env_toolCreate LinearFunctionGym for CNOT synthesis
create_clifford_env_toolCreate CliffordGym with custom gate sets
list_environments_toolList active environments
get_environment_info_toolGet environment details
delete_environment_toolRemove an environment

Training

ToolDescription
start_training_toolStart RL training (PPO or AlphaZero), supports background=True
wait_for_training_toolWait for background training to complete
batch_train_environments_toolTrain multiple environments
get_training_status_toolGet training progress and metrics
stop_training_toolStop a training session
list_training_sessions_toolList all training sessions

Synthesis

ToolDescription
synthesize_permutation_toolGenerate optimal SWAP circuit
synthesize_linear_function_toolGenerate optimal CNOT circuit
synthesize_clifford_toolGenerate optimal Clifford circuit

Model Management

ToolDescription
save_model_toolSave trained model to disk
load_model_toolLoad model from disk
list_saved_models_toolList models on disk
list_loaded_models_toolList models in memory
delete_model_toolDelete a model
get_model_info_toolGet model details

Coupling Maps

ToolDescription
create_coupling_map_toolCreate custom coupling map
extract_subtopologies_toolExtract N-qubit subtopologies from hardware
list_subtopology_shapes_toolList subtopology shapes (line, grid, etc.)
get_fake_backend_coupling_map_toolGet exact topology from fake IBM backend (no credentials needed)
list_available_fake_backends_toolList all available fake backends for offline topology access

Utility Tools

ToolDescription
generate_random_permutation_toolGenerate random permutation for testing
generate_random_linear_function_toolGenerate random linear function for testing
generate_random_clifford_toolGenerate random Clifford element for testing
convert_qpy_to_qasm3_toolConvert QPY circuit to human-readable QASM3
convert_qasm3_to_qpy_toolConvert QASM3 circuit to QPY format

Hardware Presets

PresetQubitsTopologyDescription
ibm_heron_r1133Heavy-hexIBM Heron r1 processor
ibm_heron_r2156Heavy-hexIBM Heron r2 processor
ibm_nighthawk12010x12 gridIBM Nighthawk (600% depth improvement vs Heron)
grid_3x39Grid3x3 square grid
grid_5x525Grid5x5 square grid
linear_55Line5-qubit linear chain
linear_1010Line10-qubit linear chain

Resources

URIDescription
qiskit-gym://workflowsStart here - Step-by-step workflows and quick start guide
qiskit-gym://presets/coupling-mapsAvailable hardware presets
qiskit-gym://algorithmsPPO, AlphaZero documentation
qiskit-gym://policiesBasicPolicy, Conv1dPolicy docs
qiskit-gym://environmentsEnvironment type documentation
qiskit-gym://training/sessionsActive training sessions
qiskit-gym://modelsLoaded models
qiskit-gym://server/configServer configuration

Configuration

Environment variables:

bash
# 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 limitQISKIT_GYM_MAX_QUBITS=15QISKIT_GYM_MAX_SEARCHES=10000

Development

bash
# Install with dev dependenciespip install -e ".[all]"
# Run tests./run_tests.sh
# Or manuallyuv run pytest tests/ -vuv run ruff check src testsuv run mypy src

Dependencies

License

Apache 2.0 - See LICENSE for details.

Contributing

See CONTRIBUTING.md for contribution guidelines.

來源：qiskit-gym-mcp-server/README.md，提交 373be19

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

2
  1. v0.4.2最新Oct 8, 2026
  2. v0.4.1Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分