# Qiskit Gym MCP Server

This MCP server trains RL models for quantum circuit synthesis and applies them to qubit routing, linear functions, and Clifford circuits.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 41
- Author: Qiskit
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Qiskit/mcp-servers/tree/HEAD/qiskit-gym-mcp-server
- Updated: 2026-10-08
- HTML: https://affpapa.org/en/nevibecode/mcp/qiskit-gym-mcp-server

## What it does

Qiskit Gym MCP Server exposes tools for reinforcement-learning training and quantum circuit synthesis. It covers three task types: qubit routing with SWAP gates, CNOT synthesis for linear Boolean functions, and Clifford circuit synthesis with custom gate sets.

Agents can start training in the background, poll its status, stop sessions, and save or load models. The server includes presets for IBM Heron, IBM Nighthawk, grid layouts, and linear chains. It can also extract hardware subtopologies and read exact coupling maps from fake IBM backends. Those offline topology maps require no IBM Quantum credentials.

In Claude Code, add it with `claude mcp add qiskit-gym-mcp-server -- uvx qiskit-gym-mcp-server`. TensorBoard integration exposes training progress for monitoring.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add qiskit-gym-mcp-server -- uvx qiskit-gym-mcp-server
```
uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-gym-mcp-server <command>

### Codex

**Platform CLI**
```bash
codex mcp add qiskit-gym-mcp-server -- uvx qiskit-gym-mcp-server
```
uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-gym-mcp-server <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "qiskit-gym-mcp-server": {
            "command": "uvx",
            "args": [
                "qiskit-gym-mcp-server"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-gym-mcp-server <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "qiskit-gym-mcp-server": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "qiskit-gym-mcp-server"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-gym-mcp-server <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add qiskit-gym-mcp-server uvx qiskit-gym-mcp-server
```
uvx runs the command named after the package; if the README names another one, use uvx --from qiskit-gym-mcp-server <command>

## When to use it
- train an RL model for Clifford circuit synthesis
- route qubits while reducing SWAP gates
- generate a CNOT circuit for a linear function
- extract subtopologies from an IBM hardware map
- save a trained model to disk

## Example prompts
- Create a Clifford environment on `grid_3x3` and train it with PPO.
- Get the coupling map for `fake_fez`, extract 5-qubit subtopologies, and train routing models for them.
- Start background training for a 6-qubit environment, check its status, and save the completed model.

## Similar
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [labelhead-artist-momentum](https://affpapa.org/en/nevibecode/mcp/labelhead-artist-momentum.md) — MCP server · ★ 107423
- [Agent Skills Search Server](https://affpapa.org/en/nevibecode/mcp/agent-skills-search-server.md) — MCP server · ★ 26559
- [Skyvern](https://affpapa.org/en/nevibecode/mcp/skyvern.md) — MCP server · ★ 23263
- [Nhost](https://affpapa.org/en/nevibecode/mcp/nhost.md) — MCP server · ★ 9366
- [PraisonAI](https://affpapa.org/en/nevibecode/mcp/praisonai.md) — MCP server · ★ 9289

From the same set: [qiskit/mcp-servers](https://affpapa.org/en/nevibecode/by/qiskit/mcp-servers.md) — 5 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md