io.github.Qiskit/qiskit-gym-mcp-server

Official

by Qiskit · Python

Qiskit Gym MCP Server

MCP server for qiskit-gym reinforcement learning quantum circuit synthesis

Enables reinforcement learning for quantum circuit synthesis using Qiskit.

README.md11 KBView on GitHub

Qiskit MCP Servers

A collection of Model Context Protocol (MCP) servers that give AI assistants, LLMs, and agents seamless access to IBM Quantum services and Qiskit libraries. Generate quantum code, connect to real hardware, analyze backends, execute circuits, and search Qiskit documentation — all through a standardized protocol that works with any MCP-compatible client.

Quick Start

Prerequisites

Python 3.10+ (3.11+ recommended)
IBM Quantum account and API token (only required for IBM cloud servers: Runtime, Transpiler)

Install from PyPI

bash

# Install all servers (core + community)
pip install "qiskit-mcp-servers[all]"

# Install core servers only (default, excludes community)
pip install qiskit-mcp-servers

<details> <summary>Install individual servers</summary>

bash

pip install "qiskit-mcp-servers[qiskit]"          # Qiskit server only
pip install "qiskit-mcp-servers[runtime]"         # IBM Runtime server only
pip install "qiskit-mcp-servers[transpiler]"      # IBM Transpiler server only
pip install "qiskit-mcp-servers[docs]"            # Documentation server only
pip install "qiskit-mcp-servers[gym]"             # Qiskit Gym server only (community)

</details>

Install from Source

Each server runs independently — the directory name and command are the same:

bash

cd qiskit-mcp-server  # or any server directory
pip install -e .
qiskit-mcp-server

Configuration

Servers that connect to IBM Quantum cloud services require a QISKIT_IBM_TOKEN environment variable. See each server's README for the full list of environment variables and configuration options.

bash

export QISKIT_IBM_TOKEN="your_ibm_quantum_token_here"

Client Setup

All servers are compatible with any MCP client. Pick your client below.

Claude Code

bash

# No auth required
claude mcp add qiskit -- uvx qiskit-mcp-server
claude mcp add qiskit-docs -- uvx qiskit-docs-mcp-server
claude mcp add qiskit-gym -- uvx qiskit-gym-mcp-server

# Require QISKIT_IBM_TOKEN (https://quantum.ibm.com)
claude mcp add qiskit-ibm-runtime -e QISKIT_IBM_TOKEN=$QISKIT_IBM_TOKEN -- uvx qiskit-ibm-runtime-mcp-server
claude mcp add qiskit-ibm-transpiler -e QISKIT_IBM_TOKEN=$QISKIT_IBM_TOKEN -- uvx qiskit-ibm-transpiler-mcp-server

IBM Bob

Add to your ~/.bob/settings/mcp_settings.json:

json

{
    "mcpServers": {
        "qiskit": {
            "command": "uvx",
            "args": ["qiskit-mcp-server"],
            "alwaysAllow": [],
            "disabled": false
        },
        "qiskit-docs": {
            "command": "uvx",
            "args": ["qiskit-docs-mcp-server"],
            "alwaysAllow": [],
            "disabled": false
        },
        "qiskit-gym": {
            "command": "uvx",
            "args": ["qiskit-gym-mcp-server"],
            "alwaysAllow": [],
            "disabled": false
        },
        "qiskit-ibm-runtime": {
            "command": "uvx",
            "args": ["qiskit-ibm-runtime-mcp-server"],
            "env": {
                "QISKIT_IBM_TOKEN": "<your IBM Quantum token>",
                "QISKIT_IBM_RUNTIME_MCP_INSTANCE": "<Optional: Your IBM Quantum instance CRN>"
            },
            "alwaysAllow": [],
            "disabled": false
        },
        "qiskit-ibm-transpiler": {
            "command": "uvx",
            "args": ["qiskit-ibm-transpiler-mcp-server"],
            "env": {
                "QISKIT_IBM_TOKEN": "<your IBM Quantum token>"
            },
            "alwaysAllow": [],
            "disabled": false
        }
    }
}

<details> <summary>Claude Desktop / Cline</summary>

Add to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "qiskit": {
      "command": "uvx",
      "args": ["qiskit-mcp-server"]
    },
    "qiskit-docs": {
      "command": "uvx",
      "args": ["qiskit-docs-mcp-server"]
    },
    "qiskit-gym": {
      "command": "uvx",
      "args": ["qiskit-gym-mcp-server"]
    },
    "qiskit-ibm-runtime": {
      "command": "uvx",
      "args": ["qiskit-ibm-runtime-mcp-server"],
      "env": {
        "QISKIT_IBM_TOKEN": "your_ibm_quantum_token_here"
      }
    },
    "qiskit-ibm-transpiler": {
      "command": "uvx",
      "args": ["qiskit-ibm-transpiler-mcp-server"],
      "env": {
        "QISKIT_IBM_TOKEN": "your_ibm_quantum_token_here"
      }
    }
  }
}

</details> <details> <summary>MCP Inspector (interactive testing)</summary>

bash

npx @modelcontextprotocol/inspector uvx qiskit-mcp-server
npx @modelcontextprotocol/inspector uvx qiskit-docs-mcp-server
npx @modelcontextprotocol/inspector uvx qiskit-ibm-runtime-mcp-server
# etc.

</details>

Available Servers

Core Servers

Server	Description	Directory
Qiskit MCP Server	Circuit creation, transpilation, and serialization (QASM3, QPY) using Qiskit	`qiskit-mcp-server/`
Qiskit IBM Runtime	Full access to IBM Quantum hardware via Qiskit IBM Runtime	`qiskit-ibm-runtime-mcp-server/`
Qiskit IBM Transpiler	AI-optimized circuit routing and optimization via qiskit-ibm-transpiler	`qiskit-ibm-transpiler-mcp-server/`
Qiskit Docs	Search and retrieve Qiskit documentation, guides, and API references. No auth required.	`qiskit-docs-mcp-server/`

Community Servers

Server	Description	Directory
Qiskit Gym	RL-based quantum circuit synthesis using qiskit-gym (permutation routing, linear functions, Clifford circuits)	`qiskit-gym-mcp-server/`

Removed Servers

Qiskit Code Assistant MCP Server — previously published as qiskit-code-assistant-mcp-server. Removed because the underlying Qiskit Code Assistant service has been discontinued by IBM Quantum. See the sunset announcement. The PyPI package is archived and no longer maintained.

Examples

Each server includes an examples/ directory with a Jupyter notebook (langchain_agent.ipynb) and a Python script (langchain_agent.py) showing how to build AI agents with LangChain.

The root examples/ directory contains a multi-agent Quantum Volume Finder that orchestrates multiple MCP servers to find the highest achievable Quantum Volume on IBM Quantum hardware. See the examples README for details.

Architecture

All servers are built on FastMCP and share a consistent structure:

Async-first — all tool and resource handlers are async, using FastMCP's native async support
Standalone packages — each server is an independent PyPI package with its own pyproject.toml, tests, and CI
MCP Registry — every server ships a server.json manifest for automatic discovery
Unified meta-package — qiskit-mcp-servers installs any combination via pip extras
Full MCP protocol — tools (quantum operations), resources (backend info, service status), and stdio transport

Development

Running Tests

bash

cd qiskit-mcp-server  # or any server directory
./run_tests.sh

Code Quality

Linting: ruff check and ruff format
Type checking: mypy src/
Testing: pytest with async support and coverage reporting
CI/CD: GitHub Actions for automated testing

Resources

Model Context Protocol — understanding MCP
Qiskit IBM Runtime docs — quantum cloud services
MCP Inspector — interactive testing tool
FastMCP — high-performance MCP framework
AGENTS.md — guidance for AI coding assistants (IBM Bob, Claude Code, Copilot, Cursor, and others)

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md guide for details.

License

This project is licensed under the Apache License 2.0.

Install

claude_desktop_config.json

{
  "mcpServers": {
    "qiskit-gym-mcp-server": {
      "command": "uvx",
      "args": [
        "qiskit-gym-mcp-server"
      ]
    }
  }
}