Qiskit Gym MCP Server

Qiskit Gym MCP Server

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

pip install qiskit-gym-mcp-server

Or install from source:

git clone https://github.com/Qiskit/mcp-servers

cd mcp-servers/qiskit-gym-mcp-server pip install -e .

Quick Start

Claude Desktop Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.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_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")

Tools Reference

Environment Management

Training

Synthesis

Model Management

Coupling Maps

Utility Tools

Hardware Presets

Resources

Configuration

Environment variables:

# 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

Development

# 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

Dependencies

• qiskit-gym - RL environments for quantum circuit synthesis
• FastMCP - MCP server framework
• Qiskit - Quantum computing framework
• qiskit-ibm-runtime - IBM Quantum access and fake backends

License

Apache 2.0 - See LICENSE for details.

Contributing

See CONTRIBUTING.md for contribution guidelines.