Qiskit Documentation MCP Server

qiskit-docs-mcp-server

用于查询和检索 Qiskit 文档、指南和 API 参考的 MCP 服务。

概述

Qiskit Documentation MCP Server 为 AI 助手和 Agent 提供对完整 Qiskit 文档生态系统的无缝访问。它通过标准化的 Model Context Protocol 接口，支持智能检索 SDK 模块文档、实现指南和最佳实践。

主要功能

• 📚 完整的文档访问：查询所有 Qiskit SDK 模块、附加包、API 参考、指南和教程
• 🔄 动态内容发现：自动从实时站点地图中发现可用文档 — 发布新内容时无需手动更新
• 📖 实现指南：获取优化、错误缓解、动态电路等方面的最佳实践
• 🔍 智能搜索：使用模糊匹配搜索整个 Qiskit 文档
• 🎯 无需身份验证：无需 API 令牌即可访问公开文档
• 📝 Markdown 输出：提供格式整洁的文档，可直接供 AI 使用
• ⚡ 快速检索：通过 TTL 缓存和可配置超时，高效地基于 HTTP 获取文档

组件

工具

该服务实现了三个用于访问文档的工具：

工具	描述	参数
search_docs_tool	搜索 Qiskit 文档；默认返回以查询为中心的简短片段，使响应在 Agent 重复使用时保持精简	query：搜索查询字符串 scope：搜索范围筛选器 — all（默认）、documentation、api、learning、tutorials top_k：返回的结果数上限（默认值：5，最高为 10） detail：snippet（默认，每个结果返回简短摘录）或 full（完整页面正文 — 单个页面优先使用 get_page_tool）
get_page_tool	获取任意 Qiskit 文档页面并以 Markdown 格式返回	url：完整 URL 或相对路径（例如，guides/transpile、api/qiskit/circuit） max_length：返回的字符数上限（默认值：20000，0 表示不限制） offset：用于分页的字符偏移量（默认值：0）
lookup_error_code_tool	查询 Qiskit/IBM Quantum 错误代码	code：4 位错误代码（例如，1002、7001、8004）

资源

该服务提供六个用于列出可用文档的资源。模块、附加包、指南、教程和 API 包的内容列表会从文档站点地图中动态发现并缓存；当站点地图无法访问时，则使用硬编码的后备值。

资源 URI	描述
qiskit-docs://modules	所有 Qiskit SDK 模块列表及其 URL 路径
qiskit-docs://addons	Qiskit 附加包列表及其 URL 路径
qiskit-docs://guides	实现指南和最佳实践列表
qiskit-docs://tutorials	Qiskit 教程列表及其 URL 路径
qiskit-docs://api-packages	API 包列表（runtime、transpiler、REST API 等）
qiskit-docs://error-codes	Qiskit 错误代码类别列表

资源模板

资源 URI	描述
qiskit-docs://modules/{module_name}	特定 SDK 模块的文档
qiskit-docs://guides/{guide_name}	特定实现指南
qiskit-docs://addons/{addon_name}	特定附加包的文档

前置条件

• Python 3.10 或更高版本
• uv 包管理器（推荐）
• 访问 IBM Quantum Documentation 所需的互联网连接

安装

从 PyPI 安装

最简单的安装方式是使用 pip：

pip install qiskit-docs-mcp-server

或使用 uvx（推荐）：

uvx qiskit-docs-mcp-server

从源代码安装

此项目使用 uv 管理虚拟环境和依赖项。如果尚未安装 uv，请查看 https://docs.astral.sh/uv/getting-started/installation/ 中的说明。

使用 uv 设置项目

1. 克隆代码仓库：

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

2. 初始化或同步项目：

   # This will create a virtual environment and install dependencies
   uv sync
   

配置

环境变量

可以使用环境变量配置服务：

变量	描述	默认值
QISKIT_DOCS_BASE	Qiskit 文档的基础 URL	https://quantum.cloud.ibm.com/docs/
QISKIT_HTTP_TIMEOUT	HTTP 请求超时时间（秒）	10.0
QISKIT_DOCS_CACHE_TTL	页面缓存 TTL（秒）	3600.0
QISKIT_SEARCH_CACHE_TTL	搜索/JSON 缓存 TTL（秒）	300.0
QISKIT_SEARCH_BASE_URL	搜索 API 基础 URL	https://quantum.cloud.ibm.com/

可选配置

在项目目录中创建一个 .env 文件：

# 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

快速开始

运行服务

uv run qiskit-docs-mcp-server

服务将启动并监听 MCP 连接。

与 MCP 客户端配合使用

Claude Desktop 配置

将以下内容添加到 Claude Desktop 配置文件中：

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 配置

将以下内容添加到 Cline MCP 设置中：

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

LangChain 集成示例

**注意：**运行 LangChain 示例需要安装以下依赖项：

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())

使用示例

搜索文档

# 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"])

注意（行为变更）：search_docs_tool 现在默认返回简短、以查询为中心的 片段，并将结果数限制为 top_k（默认值为 5）。在默认的 （detail="snippet"）模式下，每个结果都包含 snippet 字段，而不是完整的 text 正文，并且字段仅限于 id, url, title, pageTitle, module, section, snippet。如需恢复原有行为，请传入 detail="full"：这会还原每个 结果的完整 text 正文和所有上游字段，并且默认返回所有匹配项 （不受 top_k 限制）。在完整模式下，显式设置 top_k 仍会限制结果数， 但不会受片段模式上限的约束。若要获取单个页面的完整内容，建议使用 get_page_tool。total_results 是匹配项总数；returned_results 是实际返回的数量（在 完整模式下，除非显式设置 top_k，否则它等于 total_results）。

获取文档页面

# 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 error code 1002
result = await lookup_error_code_tool("1002")
print(result["details"])

可用文档

SDK 模块

模块	描述
circuit	量子电路的构建与操作
quantum_info	量子信息论工具
transpiler	电路转译与优化
synthesis	电路综合算法
dagcircuit	量子电路的 DAG 表示
passmanager	转译器 Pass 管理器框架
converters	电路格式转换器
compiler	高级编译例程
primitives	Sampler 和 Estimator 基元
providers	后端提供程序与作业管理
result	作业结果处理与分析
visualization	电路与结果可视化
qasm2	OpenQASM 2.0 支持
qasm3	OpenQASM 3.0 支持
qpy	Qiskit Python 序列化格式
utils	通用工具函数
exceptions	Qiskit 异常类

实现指南

指南	描述
quick-start	开始使用 Qiskit
construct-circuits	构建和操作量子电路
transpile	为目标后端转译电路
transpiler-stages	了解转译器流水线阶段
configure-error-mitigation	为原语配置误差缓解
configure-error-suppression	配置误差抑制技术
primitives	使用 Sampler 和 Estimator 原语
execution-modes	作业、会话和批处理执行模式
dynamic-circuits	电路中途测量和经典控制
functions	Qiskit Functions 概览

查看 qiskit-docs://guides 资源，获取 30 多个可用指南的完整列表。

功能

分页支持

较大的文档页面会自动分页。使用 max_length 和 offset 控制内容检索：

# 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)

包含元数据

所有响应都包含丰富的元数据：

{
    "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
    }
}

动态发现站点地图

资源列表（模块、插件、指南、教程、API 软件包）会在启动时从实时文档站点地图中自动发现。这意味着无需更改代码，服务即可适配新增内容。如果无法访问站点地图，服务会回退到 constants.py 中的硬编码值。

要根据实时站点地图更新硬编码的回退值：

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

此操作会输出更新后的常量列表，可将其复制到 constants.py 中。

HTML 转 Markdown

文档会自动从 HTML 转换为简洁的 Markdown 格式，便于 AI 使用和人类阅读。

开发

项目结构

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

运行测试

# 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

代码质量

# Format code
uv run ruff format src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type check
uv run mypy src/

示例

完整的可运行示例请参见 examples/ 目录：

• langchain_agent.py - 使用多个 LLM 提供商的 LangChain Agent
• langchain_agent.ipynb - 交互式 Jupyter 教程笔记本
• README.md - 详细的示例文档

故障排除

连接问题

问题：“无法获取文档” 解决方案：检查网络连接，并确认可以访问 https://quantum.cloud.ibm.com/docs/

超时错误

问题：“请求超时” 解决方案：增大超时值：

export QISKIT_HTTP_TIMEOUT=30.0

找不到页面

问题：get_page_tool 返回“获取失败”错误 解决方案：使用 search_docs_tool 查找正确的 URL，或查看 qiskit-docs://modules 和 qiskit-docs://guides 资源，确认有效路径

贡献

欢迎贡献！请参阅仓库根目录中的 CONTRIBUTING.md 文件，了解相关指南。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。

链接

• Qiskit 文档
• Model Context Protocol
• MCP Registry
• GitHub 仓库

支持

如有问题或疑问：

• GitHub Issues
• Qiskit Slack