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.

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

# 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)

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

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"

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

# 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

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.

• 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.

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.

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

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

• 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

• 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)

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

This project is licensed under the Apache License 2.0.