qiskit-docs-mcp-server 0.1.0

MCP server for Qiskit documentation retrieval and search

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 (circuit, primitives, transpiler, quantum_info, result, visualization)
• 📖 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 configurable timeouts

Components

Tools

The server implements five tools for documentation access:

Tool	Description	Parameters
get_sdk_module_docs_tool	Get documentation for Qiskit SDK modules	module: Module name (circuit, primitives, transpiler, quantum_info, result, visualization)
get_addon_docs_tool	Get documentation for Qiskit addon packages	addon: Addon name (e.g., sqd, cutting, mpf, obp, aqc-tensor)
get_guide_tool	Get Qiskit implementation guides and best practices	guide: Guide name (optimization, quantum-circuits, error-mitigation, dynamic-circuits, parametric-compilation, performance-tuning)
search_docs_tool	Search Qiskit documentation for relevant content	query: Search query string module: Search scope (default: "documentation")
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 four resources for listing available documentation:

Resource URI	Description
qiskit-docs://modules	List of all Qiskit SDK modules with descriptions
qiskit-docs://addons	List of Qiskit addon modules and tutorials
qiskit-docs://guides	List of implementation guides and best practices
qiskit-docs://error-codes	List of Qiskit error code categories

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
   

2. 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:

Variable	Description	Default
QISKIT_DOCS_BASE	Base URL for Qiskit documentation	https://quantum.cloud.ibm.com/docs/
QISKIT_HTTP_TIMEOUT	HTTP request timeout in seconds	10.0
QISKIT_SEARCH_BASE_URL	Search API base URL	https://quantum.cloud.ibm.com/

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

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:

pip install langchain langchain-mcp-adapters langchain-openai python-dotenv

import asyncio
from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient
from langchain_mcp_adapters.tools import load_mcp_tools
from langchain_openai import ChatOpenAI

async def main():
    # Configure MCP client
    mcp_client = MultiServerMCPClient({
        "qiskit-docs": {
            "transport": "stdio",
            "command": "qiskit-docs-mcp-server",
            "args": [],
        }
    })

    # Use persistent session for efficient tool calls
    async with mcp_client.session("qiskit-docs") as session:
        # Load MCP tools
        tools = await load_mcp_tools(session)

        # Create agent with LLM
        llm = ChatOpenAI(model="gpt-4o", temperature=0)
        agent = create_agent(
            llm,
            tools,
            system_prompt="You are a helpful quantum computing documentation assistant."
        )

        # 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

Get SDK Module Documentation

# Query circuit module documentation
result = await get_sdk_module_docs_tool("circuit")
print(result["documentation"])

Get Implementation Guide

# Get error mitigation guide
result = await get_guide_tool("error-mitigation")
print(result["documentation"])

Search Documentation

# Search for transpiler information
result = await search_docs_tool("transpiler optimization")
print(f"Found {result['total_results']} results")
for item in result["results"]:
    print(f"- {item['name']}: {item['url']}")

Available Documentation

SDK Modules

Module	Description
circuit	Quantum circuit construction and manipulation
primitives	Sampler and Estimator primitives for quantum execution
transpiler	Circuit transpilation and optimization
quantum_info	Quantum information theory utilities
result	Job result handling and analysis
visualization	Circuit and result visualization tools

Implementation Guides

Guide	Description
optimization	Quantum optimization techniques and algorithms
quantum-circuits	Circuit design patterns and best practices
error-mitigation	Error mitigation strategies for noisy quantum devices
dynamic-circuits	Mid-circuit measurements and classical control
parametric-compilation	Parameterized circuit compilation techniques
performance-tuning	Performance optimization tips and tricks

Features

Fuzzy Matching

The server includes intelligent fuzzy matching for module and guide names:

# Typo in module name - server suggests correct spelling
result = await get_sdk_module_docs_tool("circuitt")
# Returns: {"status": "error", "suggestions": ["circuit"]}

Metadata Inclusion

All responses include rich metadata:

{
    "status": "success",
    "module": "circuit",
    "documentation": "...",
    "metadata": {
        "url": "https://quantum.cloud.ibm.com/docs/api/qiskit/circuit",
        "timestamp": "2026-03-03T03:00:00Z",
        "content_type": "markdown",
        "content_length": 15420
    }
}

HTML to Markdown Conversion

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

Development

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

Module Not Found

Problem: "Module 'xyz' not found" Solution: Check available modules using the qiskit-docs://modules resource or see the Available Documentation section above

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