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.