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:

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:

   bash

   git clone https://github.com/Qiskit/mcp-servers.git
   cd mcp-servers/qiskit-docs-mcp-server
   

2. Initialize or sync the project:

   bash

   # 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"][-1].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"][0]["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": "...",
    "has_more": False,
    "total_length": 15420,
    "metadata": {
        "url": "https://quantum.cloud.ibm.com/docs/api/qiskit/circuit",
        "timestamp": "2026-03-03T03:00:00Z",
        "content_type": "markdown",
        "content_length": 15420
    }
}

Dynamic Sitemap Discovery

Resource lists (modules, addons, guides, tutorials, API packages) are automatically discovered from the live documentation sitemap at startup. This means the server adapts to new content without code changes. If the sitemap is unreachable, the server falls back to hardcoded values in constants.py.

To update the hardcoded fallback values from the live sitemap:

cd qiskit-docs-mcp-server
uv run python scripts/update_fallback_constants.py

This prints updated constant lists that can be copied into constants.py.

HTML to Markdown Conversion

Documentation is automatically converted from HTML to clean Markdown format, optimized for AI consumption and human readability.

Development

Project Structure

src/qiskit_docs_mcp_server/
├── server.py           # MCP server definition (tools, resources, prompts)
├── data_fetcher.py     # Business logic for fetching and processing documentation
├── http.py             # HTTP infrastructure: client management, caching, retries
├── sitemap.py          # Dynamic sitemap discovery and page classification
├── html_processing.py  # HTML content extraction and markdown conversion
└── constants.py        # Configuration constants and hardcoded fallback values

scripts/
└── update_fallback_constants.py  # Regenerate fallback values from live sitemap

Running Tests

# Run all tests
./run_tests.sh

# Or use pytest directly
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=src --cov-report=html

Code Quality

# Format code
uv run ruff format src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type check
uv run mypy src/

Examples

See the examples/ directory for complete working examples:

• langchain_agent.py - LangChain agent with multiple LLM providers
• langchain_agent.ipynb - Interactive Jupyter notebook tutorial
• README.md - Detailed examples documentation

Troubleshooting

Connection Issues

Problem: "Failed to fetch documentation" Solution: Check your internet connection and verify access to https://quantum.cloud.ibm.com/docs/

Timeout Errors

Problem: "Request timed out" Solution: Increase the timeout value:

export QISKIT_HTTP_TIMEOUT=30.0

Page Not Found

Problem: "Failed to fetch" error from get_page_tool Solution: Use search_docs_tool to find the correct URL, or check the qiskit-docs://modules and qiskit-docs://guides resources for valid paths

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file in the repository root for guidelines.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Links

• Qiskit Documentation
• Model Context Protocol
• MCP Registry
• GitHub Repository

Support

For issues and questions:

• GitHub Issues
• Qiskit Slack