Qiskit Gym MCP Server

io.github.QiskitPublished by GitHub account Qiskitv0.4.2Updated Oct 24, 2026

MCP server for qiskit-gym reinforcement learning quantum circuit synthesis

VerifiedSTDIODesktop onlyDeveloper ToolsAI & ML

Overview

AI-generated overview

Local MCP server that lets an assistant train reinforcement-learning agents and synthesize quantum circuits with qiskit-gym.

What you can do
  • Create, inspect and delete RL environments for permutation, linear-function and Clifford synthesis
  • Start, batch, poll, wait for and stop PPO or AlphaZero training sessions, including background runs
  • Synthesize optimal SWAP, CNOT and Clifford circuits from trained models
  • Save, load, list, inspect and delete models on disk or in memory
  • Build coupling maps, extract N-qubit subtopologies and pull exact topologies from offline IBM fake backends
  • Generate random test inputs and convert circuits between QPY and QASM3
When to use it
Useful for quantum computing research or experimentation where an assistant should set up qiskit-gym environments, run training jobs and produce optimized circuits for routing, CNOT or Clifford synthesis on grid, linear or IBM hardware topologies.
Requirements
Runs locally over stdio as a Python package (qiskit-gym-mcp-server, e.g. via uvx or pip) and is intended for desktop clients. No credentials are needed, including for IBM fake-backend topologies. Optional environment variables set model and TensorBoard directories and training limits such as QISKIT_GYM_MAX_QUBITS.
Before you install
Training is compute-intensive and can run long; background sessions and limits such as QISKIT_GYM_MAX_ITERATIONS and QISKIT_GYM_MAX_QUBITS control cost. Tools write to disk: models are saved under QISKIT_GYM_MODEL_DIR and logs under QISKIT_GYM_TENSORBOARD_DIR, and delete tools remove environments and models. No authentication is declared.

Installation

In SourceWeft

  1. Open Qiskit Gym MCP Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

Source: qiskit-gym-mcp-server/README.md at commit 373be19

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.4.2LatestOct 8, 2026
  2. v0.4.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts