Qiskit Gym MCP Server

MCP server for qiskit-gym reinforcement learning quantum circuit synthesis

Connector by Qiskit · GitHub account verified by the MCP Registry

IndexedApache-2.0Local (stdio)★ 41

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/qiskit-qiskit-gym-mcp-server

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

About

MCP server for qiskit-gym reinforcement learning quantum circuit synthesis

Use cases: code-generation

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list, install config and code. Checked Oct 25, 2026.

Tools: 25 read · 10 write · 2 delete
Secrets: None asked for
Install scripts: None found
Runs as: Python package

Tools by what they do 37

Read from the source code; the running server may list different tools.

Read 25 · Look things up without changing anything.

convert_qasm3_to_qpy_tool
convert_qpy_to_qasm3_tool
extract_subtopologies_tool
generate_random_clifford_tool
generate_random_linear_function_tool
generate_random_permutation_tool
get_environment_info_tool
get_fake_backend_coupling_map_tool
get_model_info_tool
get_tensorboard_metrics_tool
get_tensorboard_status_tool
get_training_metrics_tool

Show 13 more tools

get_training_status_tool
list_available_fake_backends_tool
list_environments_tool
list_loaded_models_tool
list_saved_models_tool
list_subtopology_shapes_tool
list_tensorboard_experiments_tool
list_training_sessions_tool
load_model_tool
synthesize_clifford_tool
synthesize_linear_function_tool
synthesize_permutation_tool
wait_for_training_tool

Write 10 · Create, change, send or run things.

batch_train_environments_tool
create_clifford_env_tool
create_coupling_map_tool
create_linear_function_env_tool
create_permutation_env_tool
save_model_tool
start_tensorboard_tool
start_training_tool
stop_tensorboard_tool
stop_training_tool

Delete 2 · Delete, drop, revoke or wipe things.

delete_environment_tool
delete_model_tool

Network hosts it talks to 1

github.com · found in code

Files it touches

Your home directory (~)

Tools (37)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

batch_train_environments_tool
Train multiple environments in sequence. Useful for training models across multiple topologies or subtopologies extracted from hardware. Args: env_ids: List of environment IDs to train algorithm: RL algorithm to use policy: Neural network policy architecture num_iterations: Number of iterations per environment tensorboard_prefix: Prefix for TensorBoard experiment names background: If True, start all training in background and return immediately. Use get_training_status_tool or wait_for_training_tool to monitor. Returns: If background=False: Dict with resu…
convert_qasm3_to_qpy_tool
Convert a QASM3 (or QASM2) circuit to base64-encoded QPY format. Use this tool to convert human-readable QASM circuits to QPY format, which preserves full circuit fidelity. The QPY output can be used with synthesis tools that may require circuit input. Args: circuit_qasm: OpenQASM 3.0 or 2.0 circuit string Returns: Dict with 'status' and 'circuit_qpy' (base64-encoded QPY string).
convert_qpy_to_qasm3_tool
Convert a QPY circuit to human-readable QASM3 format. Use this tool to view the contents of a QPY circuit output from synthesis tools (like synthesize_permutation, synthesize_linear_function, synthesize_clifford) in a human-readable OpenQASM 3.0 format. Args: circuit_qpy: Base64-encoded QPY circuit string (from synthesis output) Returns: Dict with 'status' and 'qasm3' (the human-readable circuit string).
create_clifford_env_tool
Create a CliffordGym environment for learning Clifford circuit synthesis. The environment learns to synthesize optimal implementations of Clifford group elements using a customizable gate set. Args: num_qubits: Number of qubits for the environment coupling_map: Custom coupling map (optional) preset: Hardware preset name (optional) gateset: Custom gate set. Can be: - List of gate names: ["H", "S", "CX"] (applied to all qubits/edges) - List of dicts: [{"gate": "H", "qubits": [0]}, {"gate": "CX", "qubits": [0, 1]}] Returns: Dict with env_id, environment info…
create_coupling_map_tool
Create a custom coupling map. Args: edges: Custom edges as [[q1, q2], ...] (mutually exclusive with topology) topology: Topology type ("grid", "line") (mutually exclusive with edges) num_qubits: Number of qubits (for line topology) rows: Number of rows (for grid topology) cols: Number of columns (for grid topology) bidirectional: Whether edges are bidirectional (default: True) Returns: Dict with coupling map info and edges.
create_linear_function_env_tool
Create a LinearFunctionGym environment for learning CNOT synthesis. The environment learns to decompose linear Boolean functions into efficient quantum circuits using CNOT gates. Args: coupling_map: Custom coupling map as list of [qubit1, qubit2] edges. preset: Hardware preset name (e.g., "ibm_nighthawk", "grid_3x3") basis_gates: Optional list of basis gates (default: ["cx"]) Returns: Dict with env_id, environment info on success.
create_permutation_env_tool
Create a PermutationGym environment for learning qubit routing with SWAP gates. Use this to create an RL environment that learns to implement arbitrary qubit permutations using minimal SWAP gates on constrained coupling maps. Args: coupling_map: Custom coupling map as list of [qubit1, qubit2] edges. Example: [[0,1], [1,2], [2,3]] for a linear chain. preset: Hardware preset name (use instead of coupling_map). Options: "ibm_heron_r1", "ibm_heron_r2", "ibm_nighthawk", "grid_3x3", "grid_5x5", "linear_5", "linear_10" Returns: Dict with env_id, env_type…
delete_environment_tool
Delete an environment. Args: env_id: Environment ID to delete Returns: Dict with deletion status.
delete_model_tool
Delete a model. Args: model_name: Name of the model to delete delete_files: If True, also delete saved files from disk Returns: Dict with deletion status.
extract_subtopologies_tool
Extract connected subtopologies of N qubits from a hardware preset. Use this to find all unique connected subgraphs of a specified size from a larger coupling map. Essential for training RL models on subtopologies of real quantum hardware like IBM Nighthawk. Args: preset: Hardware preset name (e.g., "ibm_nighthawk", "ibm_heron_r1") edges: Custom coupling map edges (alternative to preset) num_qubits: Number of qubits for subtopologies (default: 4) max_subtopologies: Maximum number of subtopologies to return (default: 50) Returns: Dict with list of subtopologies, each cont…
generate_random_clifford_tool
Generate a random Clifford element for testing. Args: num_qubits: Number of qubits Returns: Dict with random Clifford tableau.
generate_random_linear_function_tool
Generate a random invertible linear function for testing. Args: num_qubits: Number of qubits Returns: Dict with random linear function matrix.
generate_random_permutation_tool
Generate a random permutation for testing synthesis. Args: num_qubits: Number of qubits Returns: Dict with random permutation.
get_environment_info_tool
Get detailed information about a specific environment. Args: env_id: Environment ID Returns: Dict with environment details.
get_fake_backend_coupling_map_tool
Get the exact coupling map from a fake IBM backend (no credentials needed). Use this to get exact IBM Quantum hardware topologies without needing IBM Quantum credentials. This is the recommended way to get accurate topologies for offline development. Args: backend_name: Backend name (e.g., "ibm_fez", "ibm_brisbane", "ibm_boston", "ibm_sherbrooke"). Use list_available_fake_backends to see all options. Returns: Dict with exact coupling map edges that can be used with create_*_env tools. Example: 1. get_fake_backend_coupling_map_tool("ibm_fez") -> edges 2. create_cliff…

Show 22 more tools

get_model_info_tool
Get detailed information about a model. Args: model_id: Model ID (for loaded models) model_name: Model name (can also check saved models on disk) Returns: Dict with model details.
get_tensorboard_metrics_tool
Get training metrics from TensorBoard logs for historical runs. Use this to read metrics from past training runs that are no longer in the active session list. Use list_tensorboard_experiments_tool to see available experiments. Args: experiment_name: Name of the TensorBoard experiment (e.g., "linear_function_train_0001_abc123"). tensorboard_path: Direct path to TensorBoard logs (alternative to name). Returns: Dict with metrics progression (difficulty, success, reward by step) and final values. Example: 1. list_tensorboard_experiments_tool() -> see available expe…
get_tensorboard_status_tool
Check the status of the TensorBoard process. Returns whether TensorBoard is running and on which port. Returns: Dict with running status, port, and URL if running.
get_training_metrics_tool
Get detailed training metrics from TensorBoard logs. Returns the progression of difficulty, success rate, and reward throughout training. Use this after training completes to understand how well the model trained and what difficulty level it reached. Args: session_id: Training session ID Returns: Dict with: - metrics: Full progression data (difficulty, success, reward by step) - final_difficulty: The highest difficulty level reached - final_success: The final success rate achieved - final_success_percent: Success rate as percentage string Example: After training…
get_training_status_tool
Get the status and metrics of a training session. Args: session_id: Training session ID Returns: Dict with session status, progress, and metrics.
list_available_fake_backends_tool
List all available fake backends for offline topology access. Returns a list of IBM Quantum backends that have fake versions available in qiskit-ibm-runtime. These provide exact coupling maps without needing IBM Quantum credentials. Returns: Dict with list of backends, their qubit counts, and usage instructions.
list_environments_tool
List all active RL environments. Returns: Dict with list of environments and their info.
list_loaded_models_tool
List all models currently loaded in memory. Args: filter_type: Optional filter by env_type or model name prefix Returns: Dict with list of loaded models.
list_saved_models_tool
List all models saved to disk. Returns: Dict with list of saved models.
list_subtopology_shapes_tool
List available subtopology shapes for a given hardware and qubit count. Summarizes the types of subtopologies available (line, grid, star, etc.) without returning all edges. Args: preset: Hardware preset name num_qubits: Number of qubits for subtopologies Returns: Dict with shape counts and example subtopologies.
list_tensorboard_experiments_tool
List available TensorBoard experiments from past training runs. Returns a list of experiment names that can be used with get_tensorboard_metrics_tool to view historical training metrics. Returns: Dict with list of experiment names (newest first).
list_training_sessions_tool
List all training sessions. Returns: Dict with list of training sessions.
load_model_tool
Load a saved model from disk. Args: model_name: Name of the model to load Returns: Dict with model_id and model info.
save_model_tool
Save a trained model to disk. Save by session_id (from just-completed training) or model_id (loaded model). Args: session_id: Training session ID (from start_training result) model_id: Model ID (alternative to session_id) model_name: Name to save as (defaults to auto-generated) Returns: Dict with save status and file paths.
start_tensorboard_tool
Start TensorBoard to visualize training metrics. Launches TensorBoard as a background process using the configured QISKIT_GYM_TENSORBOARD_DIR as the log directory. Args: port: The port to run TensorBoard on (default: 6006) Returns: Dict with status and TensorBoard URL on success. Note: Use stop_tensorboard_tool to stop the TensorBoard process when done.
start_training_tool
Start training an RL agent on a created environment. This initiates training that learns to synthesize optimal circuits. Args: env_id: Environment ID from create_*_env_tool algorithm: RL algorithm to use: - "ppo": Proximal Policy Optimization (recommended, faster) - "alphazero": AlphaZero-style MCTS (better for complex problems) policy: Neural network policy architecture: - "basic": Simple feedforward network (faster, good for small problems) - "conv1d": 1D convolutional network (better for larger problems) num_iterations: Number of training it…
stop_tensorboard_tool
Stop the running TensorBoard process. Terminates the TensorBoard process that was started with start_tensorboard_tool. Returns: Dict with status message indicating whether TensorBoard was stopped.
stop_training_tool
Stop a training session. Args: session_id: Training session ID to stop Returns: Dict with stop status.
synthesize_clifford_tool
Synthesize an optimal quantum circuit for a Clifford operation. Uses a trained CliffordGym model to find an optimal Clifford implementation. Args: model_id: ID of a loaded CliffordGym model clifford_tableau: Clifford tableau in standard (2N+1 x 2N) format, or dict with "destab" and "stab" matrices. num_searches: Number of search attempts. Max: 10000 deterministic: If True, use deterministic action selection Returns: Dict with circuit_qpy (base64-encoded), metrics on success.
synthesize_linear_function_tool
Synthesize an optimal quantum circuit for a linear Boolean function. Uses a trained LinearFunctionGym model to find an optimal CNOT circuit. Args: model_id: ID of a loaded LinearFunctionGym model linear_function: NxN binary matrix representing the linear function. Entry [i][j]=1 means output i depends on input j (XOR). num_searches: Number of search attempts. Max: 10000 deterministic: If True, use deterministic action selection Returns: Dict with circuit_qpy (base64-encoded), metrics on success.
synthesize_permutation_tool
Synthesize an optimal quantum circuit for a qubit permutation. Uses a trained PermutationGym model to find an optimal SWAP gate sequence that implements the desired qubit permutation on the coupling map. Args: model_id: ID of a loaded PermutationGym model permutation: Target permutation as list of qubit indices. Example: [2, 0, 1] means qubit 0 -> position 2, qubit 1 -> position 0 num_searches: Number of search attempts. Higher = better results. Max: 10000 deterministic: If True, use deterministic action selection Returns: Dict with circuit_qpy (base64-encoded), …
wait_for_training_tool
Wait for a background training session to complete. Blocks until training completes, fails, or times out. Use this after starting training with background=True. Args: session_id: Training session ID to wait for timeout: Maximum time to wait in seconds (default: 600 = 10 minutes) Returns: Dict with final training status. If completed, includes model_id for synthesis. Example workflow: 1. start_training_tool(env_id, background=True) -> session_id 2. wait_for_training_tool(session_id) -> model_id 3. synthesize_*_tool(model_id, ...) -> circuit

Signals

Stars: 41
Forks: 21
Open issues: 1
Contributors: 12
Weekly downloads: 1,598
Last commit (this folder): Oct 7, 2026 (21 days ago)
Last release: Oct 8, 2026 (20 days ago)
Last package publish: Oct 8, 2026 (20 days ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name: io.github.Qiskit/qiskit-gym-mcp-server
Version: 0.4.2
Auth: No auth
Packages: pypi qiskit-gym-mcp-server
License: Apache-2.0
Repository: github.com/Qiskit/mcp-servers
Website: github.com/Qiskit/mcp-servers/tree/main/qiskit-gym-mcp-server
First seen: Oct 24, 2026
Last checked: Oct 24, 2026
Source: Official MCP Registry github-graphql

More from Qiskit

Cite this page

Qiskit Gym MCP Server. Agent Mart. https://agentmart.dev/connectors/qiskit-qiskit-gym-mcp-server (last updated 2026-10-24)