Qiskit Gym MCP Server

Tests License Python Version Code style: ruff Type checked: mypy

qiskit-mcp-server qiskit-ibm-runtime-mcp-server qiskit-ibm-transpiler-mcp-server qiskit-docs-mcp-server qiskit-gym-mcp-server

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

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

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

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)

Install from Source

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

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.

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

Claude Code Video

# 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

IBM Bob Video

Add to your ~/.bob/settings/mcp_settings.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
        }
    }
}

{
  "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"
      }
    }
  }
}

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.

Available Servers

Core Servers

Community Servers

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

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.