# Qiskit MCP Servers
[](https://github.com/Qiskit/mcp-servers/actions/workflows/test.yml)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.python.org/downloads/)
[](https://github.com/astral-sh/ruff)
[](http://mypy-lang.org/)
[](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-mcp-server)
[](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-ibm-runtime-mcp-server)
[](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-ibm-transpiler-mcp-server)
[](https://registry.modelcontextprotocol.io/?q=io.github.Qiskit%2Fqiskit-docs-mcp-server)
[](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
```
Install individual servers
```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)
```
### 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
[](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
[](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": "",
"QISKIT_IBM_RUNTIME_MCP_INSTANCE": ""
},
"alwaysAllow": [],
"disabled": false
},
"qiskit-ibm-transpiler": {
"command": "uvx",
"args": ["qiskit-ibm-transpiler-mcp-server"],
"env": {
"QISKIT_IBM_TOKEN": ""
},
"alwaysAllow": [],
"disabled": false
}
}
}
```
Claude Desktop / Cline
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"
}
}
}
}
```
MCP Inspector (interactive testing)
```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.
```
## 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**.