Metadata-Version: 2.4
Name: qiskit-mcp-servers
Version: 0.11.0
Summary: Model Context Protocol servers for IBM Quantum services and Qiskit
Project-URL: Homepage, https://github.com/Qiskit/mcp-servers
Project-URL: Repository, https://github.com/Qiskit/mcp-servers
Project-URL: Documentation, https://github.com/Qiskit/mcp-servers#readme
Project-URL: Bug Tracker, https://github.com/Qiskit/mcp-servers/issues
Author-email: "Quantum+AI Team. IBM Quantum" <Quantum.Plus.AI@ibm.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,ibm,mcp,qiskit,quantum,quantum-computing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <3.15,>=3.10
Requires-Dist: qiskit-docs-mcp-server>=0.1.1
Requires-Dist: qiskit-ibm-runtime-mcp-server>=0.5.0
Requires-Dist: qiskit-ibm-transpiler-mcp-server>=0.3.1
Requires-Dist: qiskit-mcp-server>=0.2.0
Provides-Extra: all
Requires-Dist: qiskit-docs-mcp-server>=0.1.1; extra == 'all'
Requires-Dist: qiskit-gym-mcp-server>=0.3.0; extra == 'all'
Requires-Dist: qiskit-ibm-runtime-mcp-server>=0.5.0; extra == 'all'
Requires-Dist: qiskit-ibm-transpiler-mcp-server>=0.3.1; extra == 'all'
Requires-Dist: qiskit-mcp-server>=0.2.0; extra == 'all'
Provides-Extra: community
Requires-Dist: qiskit-gym-mcp-server>=0.3.0; extra == 'community'
Provides-Extra: docs
Requires-Dist: qiskit-docs-mcp-server>=0.1.1; extra == 'docs'
Provides-Extra: gym
Requires-Dist: qiskit-gym-mcp-server>=0.3.0; extra == 'gym'
Provides-Extra: qiskit
Requires-Dist: qiskit-mcp-server>=0.2.0; extra == 'qiskit'
Provides-Extra: runtime
Requires-Dist: qiskit-ibm-runtime-mcp-server>=0.5.0; extra == 'runtime'
Provides-Extra: transpiler
Requires-Dist: qiskit-ibm-transpiler-mcp-server>=0.3.1; extra == 'transpiler'
Description-Content-Type: text/markdown

# Qiskit MCP Servers

[![Tests](https://github.com/Qiskit/mcp-servers/actions/workflows/test.yml/badge.svg)](https://github.com/Qiskit/mcp-servers/actions/workflows/test.yml)
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Type checked: mypy](https://img.shields.io/badge/type%20checked-mypy-blue.svg)](http://mypy-lang.org/)

[![qiskit-mcp-server](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%2Fio.github.Qiskit%252Fqiskit-mcp-server%2Fversions%2Flatest&query=%24.server.version&label=qiskit-mcp-server&logo=modelcontextprotocol)](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-mcp-server)
[![qiskit-ibm-runtime-mcp-server](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%2Fio.github.Qiskit%252Fqiskit-ibm-runtime-mcp-server%2Fversions%2Flatest&query=%24.server.version&label=qiskit-ibm-runtime-mcp-server&logo=modelcontextprotocol)](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-ibm-runtime-mcp-server)
[![qiskit-ibm-transpiler-mcp-server](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%2Fio.github.Qiskit%252Fqiskit-ibm-transpiler-mcp-server%2Fversions%2Flatest&query=%24.server.version&label=qiskit-ibm-transpiler-mcp-server&logo=modelcontextprotocol)](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-ibm-transpiler-mcp-server)
[![qiskit-docs-mcp-server](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%2Fio.github.Qiskit%252Fqiskit-docs-mcp-server%2Fversions%2Flatest&query=%24.server.version&label=qiskit-docs-mcp-server&logo=modelcontextprotocol)](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-docs-mcp-server)
[![qiskit-gym-mcp-server](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fregistry.modelcontextprotocol.io%2Fv0.1%2Fservers%2Fio.github.Qiskit%252Fqiskit-gym-mcp-server%2Fversions%2Flatest&query=%24.server.version&label=qiskit-gym-mcp-server&logo=modelcontextprotocol)](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-gym-mcp-server)

A collection of [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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](https://quantum.ibm.com) (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

[![Claude Code Video](https://github.com/user-attachments/assets/161797b0-59d9-4632-bafa-12d50bfef226)](https://github.com/user-attachments/assets/161797b0-59d9-4632-bafa-12d50bfef226)

```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

[![IBM Bob Video](https://github.com/user-attachments/assets/b1e9cfc4-c729-4050-9998-815f6b63bacd)](https://github.com/user-attachments/assets/b1e9cfc4-c729-4050-9998-815f6b63bacd)

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](https://github.com/Qiskit/qiskit) | [`qiskit-mcp-server/`](./qiskit-mcp-server/) |
| **Qiskit IBM Runtime** | Full access to IBM Quantum hardware via [Qiskit IBM Runtime](https://github.com/Qiskit/qiskit-ibm-runtime/) | [`qiskit-ibm-runtime-mcp-server/`](./qiskit-ibm-runtime-mcp-server/) |
| **Qiskit IBM Transpiler** | AI-optimized circuit routing and optimization via [qiskit-ibm-transpiler](https://github.com/Qiskit/qiskit-ibm-transpiler) | [`qiskit-ibm-transpiler-mcp-server/`](./qiskit-ibm-transpiler-mcp-server/) |
| **Qiskit Docs** | Search and retrieve [Qiskit documentation](https://quantum.cloud.ibm.com/docs/), guides, and API references. No auth required. | [`qiskit-docs-mcp-server/`](./qiskit-docs-mcp-server/) |

### Community Servers

| Server | Description | Directory |
|--------|-------------|-----------|
| **Qiskit Gym** | RL-based quantum circuit synthesis using [qiskit-gym](https://github.com/rl-institut/qiskit-gym) (permutation routing, linear functions, Clifford circuits) | [`qiskit-gym-mcp-server/`](./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](https://quantum.cloud.ibm.com/announcements/en/product-updates/2026-04-28-qiskit-code-assistant-service-to-sunset). 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/`](./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](./examples/README.md) for details.

## Architecture

All servers are built on [FastMCP](https://github.com/jlowin/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`](https://registry.modelcontextprotocol.io/) 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](https://modelcontextprotocol.io/introduction) — understanding MCP
- [Qiskit IBM Runtime docs](https://quantum.cloud.ibm.com/docs/en/api/qiskit-ibm-runtime) — quantum cloud services
- [MCP Inspector](https://github.com/modelcontextprotocol/inspector) — interactive testing tool
- [FastMCP](https://github.com/jlowin/fastmcp) — high-performance MCP framework
- [AGENTS.md](AGENTS.md) — guidance for AI coding assistants (IBM Bob, Claude Code, Copilot, Cursor, and others)

## Contributing

Contributions are welcome! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) guide for details.

## License

This project is licensed under the **Apache License 2.0**.
