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 分