Qiskit Documentation MCP Server

qiskit-docs-mcp-server

MCP server for querying and retrieving Qiskit documentation, guides, and API references.

Overview

The Qiskit Documentation MCP Server provides AI assistants and agents with seamless access to the complete Qiskit documentation ecosystem. It enables intelligent retrieval of SDK module documentation, implementation guides, and best practices through a standardized Model Context Protocol interface.

Key Features

• 📚 Complete Documentation Access: Query all Qiskit SDK modules, addon packages, API references, guides, and tutorials
• 🔄 Dynamic Content Discovery: Automatically discovers available documentation from the live sitemap — no manual updates needed when new content is published
• 📖 Implementation Guides: Access best practices for optimization, error mitigation, dynamic circuits, and more
• 🔍 Smart Search: Search across the entire Qiskit documentation with fuzzy matching
• 🎯 No Authentication Required: Public documentation access without API tokens
• 📝 Markdown Output: Clean, formatted documentation ready for AI consumption
• ⚡ Fast Retrieval: Efficient HTTP-based documentation fetching with TTL caching and configurable timeouts

Components

Tools

The server implements three tools for documentation access:

| search_docs_tool | Search the Qiskit documentation; returns short query-centered snippets by default so the response stays compact for repeated agent use | query: Search query string scope: Search scope filter — all (default), documentation, api, learning, tutorials top_k: Max results to return (default: 5, capped at 10) detail: snippet (default, short excerpt per result) or full (full page body — prefer get_page_tool for a single page) | | get_page_tool | Fetch any Qiskit documentation page and return as markdown | url: Full URL or relative path (e.g., guides/transpile, api/qiskit/circuit) max_length: Max characters to return (default: 20000, 0 for unlimited) offset: Character offset for pagination (default: 0) | | lookup_error_code_tool | Look up a Qiskit/IBM Quantum error code | code: 4-digit error code (e.g., 1002, 7001, 8004) |

Resources

The server provides six resources for listing available documentation. Content lists for modules, addons, guides, tutorials, and API packages are dynamically discovered from the documentation sitemap and cached, with hardcoded fallback values used when the sitemap is unreachable.

Resource Templates

Prerequisites

• Python 3.10 or higher
• uv package manager (recommended)
• Internet connection to access IBM Quantum Documentation

Installation

Install from PyPI

The easiest way to install is via pip:

pip install qiskit-docs-mcp-server

Or using uvx (recommended):

uvx qiskit-docs-mcp-server

Install from Source

This project uses uv for virtual environments and dependencies management. If you don't have uv installed, check out the instructions in https://docs.astral.sh/uv/getting-started/installation/

Setting up the Project with uv

1. Clone the repository:

   git clone https://github.com/Qiskit/mcp-servers.git

cd mcp-servers/qiskit-docs-mcp-server

1. Initialize or sync the project:

   # This will create a virtual environment and install dependencies

uv sync

Configuration

Environment Variables

The server can be configured using environment variables:

Optional Configuration

Create a .env file in the project directory:

# Optional: Customize documentation URLs

QISKIT_DOCS_BASE=https://quantum.cloud.ibm.com/docs/ QISKIT_HTTP_TIMEOUT=15.0 QISKIT_DOCS_CACHE_TTL=3600.0 QISKIT_SEARCH_CACHE_TTL=300.0

Quick Start

Running the Server

uv run qiskit-docs-mcp-server

The server will start and listen for MCP connections.

Using with MCP Clients

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{

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

Cline Configuration

Add to your Cline MCP settings:

{

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

LangChain Integration Example

Note: To run LangChain examples you will need to install the dependencies:

`bash

pip install langchain-mcp-adapters langchain-openai langgraph

`

import asyncio

from langchain_mcp_adapters.client import MultiServerMCPClient from langchain_openai import ChatOpenAI from langgraph.prebuilt import create_react_agent

async def main():

Configure MCP client

async with MultiServerMCPClient( { "qiskit-docs": { "command": "qiskit-docs-mcp-server", "args": [], "transport": "stdio", } } ) as client:

Create agent with LLM and MCP tools

agent = create_react_agent( ChatOpenAI(model="gpt-4o"), client.get_tools(), )

Query documentation

response = await agent.ainvoke( {"messages": [("user", "How do I create a quantum circuit in Qiskit?")]} ) print(response"messages".content)

asyncio.run(main())

Usage Examples

Search Documentation

# Search returns short snippets (not full pages) — cheap to call inside an agent

result = await search_docs_tool("transpiler optimization") print(f"Showing {result['returned_results']} of {result['total_results']} matches") for item in result["results"]: print(f"- {item['title']}: {item['url']}") print(f" {item['snippet']}")

Then fetch the full content of the one page you want

page = await get_page_tool(result"results"["url"]) print(page["documentation"])

Note (behavior change): search_docs_tool now returns short, query-centered

snippets by default and caps results to top_k (default 5). In default

(detail="snippet") mode each result carries a snippet field — not the full

text body — and is limited to `id, url, title, pageTitle, module, section,

snippet. For the original behavior, pass detail="full"`: it restores each

result's full text body and all upstream fields and returns every match

by default (no top_k cap) — an explicit top_k still limits the count in

full mode but is not clamped to the snippet-mode ceiling. Prefer get_page_tool

for a single page's full content. total_results is the grand total of matches;

returned_results is the count actually returned (equal to total_results in

full mode unless you set an explicit top_k).

Fetch a Documentation Page

# Fetch circuit module API reference

result = await get_page_tool("api/qiskit/circuit") print(result["documentation"])

Fetch with pagination for large pages

result = await get_page_tool("api/qiskit/circuit", max_length=5000) if result["has_more"]: next_page = await get_page_tool("api/qiskit/circuit", offset=result["next_offset"])

Look Up an Error Code

# Look up error code 1002

result = await lookup_error_code_tool("1002") print(result["details"])

Available Documentation

SDK Modules

Implementation Guides

See the qiskit-docs://guides resource for the complete list of 30+ available guides.

Features

Pagination Support

Large documentation pages are automatically paginated. Use max_length and offset to control content retrieval:

# Fetch first 5000 characters

result = await get_page_tool("api/qiskit/circuit", max_length=5000)

result["has_more"] == True, result["next_offset"] == 5000

Fetch unlimited content

result = await get_page_tool("api/qiskit/circuit", max_length=0)

Metadata Inclusion

All responses include rich metadata:

{

"status": "success", "url": "https://quantum.cloud.ibm.com/docs/api/qiskit/circuit", "documentation": "