Python Docs MCP Server

python-docs-mcp-server

对于编写 Python 的 AI 编码 Agent，python-docs-mcp-server 是权威的 Python 标准库参考：符号、章节和版本精准无误；离线运行，始终免费，始终采用 MIT 许可，节省令牌。

当 Agent 需要查询 asyncio.TaskGroup 的签名、pathlib.Path 的语义，或了解 3.12 版本中的变化时，它就能派上用场——无需抓取网页，无需托管 API，也不会像向量存储那样虚构章节锚点。它只会从 docs.python.org 中检索索引内容，按符号或查询返回，并限定为你实际使用的版本。

为什么要构建这个工具

上下文长，不等于上下文好用。Lost in the Middle 研究（Liu 等人，2023 年）发现，模型难以利用长输入中间部分埋藏的相关信息。将整页文档粘贴给模型，容易导致这一问题。只返回确切的符号、章节和版本，就能让答案处于简短且信息密集的上下文中。

通用文档检索不太适合回答 Python 标准库问题：

• asyncio.TaskGroup 应解析到实际符号，而不是模糊的页面匹配结果
• Python 版本很重要（3.12 和 3.13 的内容并不总是相同）
• 只需一个章节就能回答问题时，抓取整页会浪费令牌
• 官方文档具有权威性，但没有以 MCP 服务的形式提供

此服务在本地为官方文档建立索引，并提供一组简洁的 MCP 工具，用于查询和检索章节。

为什么使用它

• 无需管理 API 密钥
• 查询针对本地索引运行，而非托管的文档 API
• 结果来自官方 Python 文档
• 此服务在运行时为只读
• 在严格的环境中，需要审核的依赖项更少

你将获得

• 通过 Python objects.inv 查找符号
• 检索页面和章节，并支持截断和分页
• 本地 SQLite + FTS5 索引；运行时不会抓取网页
• 返回你为每个 Python 版本建立索引的结果
• 七种只读 MCP 工具

快速示例

提示词

asyncio.TaskGroup 在 Python 3.13 中有什么作用？

典型流程

1. search_docs("asyncio.TaskGroup", kind="symbol", version="3.13")
2. 使用最佳匹配结果返回的 slug 和锚点调用 get_docs(...)

结果

模型会获得匹配的符号和相关文档章节，而非整页内容。

30 秒演示

向你的 MCP 客户端提问：

在 Python 3.13 中，我该如何使用 asyncio.TaskGroup？它与旧版 asyncio 模式相比有哪些变化？

如果配置正常，客户端应针对这个确切符号使用 search_docs， 然后使用 get_docs 获取匹配章节。它不会返回通用网页搜索结果或 整页文档，而是会获取适用于所请求 Python 版本的官方标准库文本， 并截取与问题相关的章节。

安装

直接使用 uvx 运行：

uvx python-docs-mcp-server --version

或者使用 pipx 安装一次：

pipx install python-docs-mcp-server

---

如果已安装 uv，但 uv 命令不在 PATH 中，请重新打开 Shell，或在本地贡献者命令中使用 python -m uv ... 作为备用方式。

搜索结果行为

对于带有显式版本的 kind="auto"，如果搜索结果非空且还有剩余结果位， 当提示词中包含该版本下一个已知的限定标识符时，搜索结果可以追加一个 精确的索引目标。原有命中项、摘要、分数、顺序和备注均会保留。完整结果、 有歧义的标识符、其他类型以及未指定版本的查询均不变；现有的空结果回退 行为也不变。规范位置会去重，包括索引别名。

只有当使用 Pydantic 的紧凑 model_dump_json() 序列化的完整拟议响应 不超过 8000 UTF-8 字节时，才会追加该结果。这不是全局搜索上限：超出 大小限制的原始响应保持不变。它与限制内容字符数的 get_docs(max_chars=8000) 不同。

首次运行

构建本地文档索引：

uvx python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14

如果你已持久安装软件包，可以省略 uvx 前缀：

python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14

首次构建会下载 Python 的 objects.inv 文件，克隆 CPython 文档源码， 运行 sphinx-build -b json，并将 SQLite 索引写入本地缓存。整个过程可能需要几分钟。

Python 3.15 文档（选择加入）

源码固定的文档目标包括 Python 3.10–3.15。若要将 3.15 与 3.14 一同建立索引，请显式运行：

uvx python-docs-mcp-server build-index --versions 3.14,3.15

构建会用所请求的版本替换本地索引；请包含所有想要保留的版本。上面的 首次运行示例有意保持不变。构建器仍会将最高的所请求版本设为索引默认版本； 添加此目标不会在现有索引中选择 3.15。未指定版本的 get_docs 会使用已配置或检测到的默认版本，而未指定版本的搜索会跨已索引版本进行。传入 version="3.15" 可获取仅针对 3.15 的回答。list_versions 会报告实际索引中的版本，而不是所有构建目标；显式指定未建立索引的版本会引发错误，不会回退到较旧的文档。

这是文档覆盖范围，并不意味着该服务能在 Python 3.15 上运行，也不表示已使用某个指定的 MCP 客户端进行测试。成功构建后，查询仍为离线且只读。在建立索引之前，请直接参阅官方 3.15 文档。

3.15 目标使用 CPython 标签 v3.15.0、提交 d220409a13b77de7a6c30abe16ea90db01528edc 和 Sphinx 8.2.3。 有关显式版本和比较示例，请参阅集成检查。

配置 MCP 客户端

Claude Code

此仓库包含项目范围的 .mcp.json，供支持已纳入仓库的 MCP 服务配置的客户端使用。它指向已发布的软件包：

{
  "mcpServers": {
    "python-docs": {
      "type": "stdio",
      "command": "uvx",
      "args": ["python-docs-mcp-server"]
    }
  }
}

在预期文档查询返回基于语料库的结果之前，请先使用上面的首次运行命令构建本地文档索引。

Claude Desktop

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

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

Linux： ~/.config/Claude/claude_desktop_config.json

Windows： %APPDATA%\\Claude\\claude_desktop_config.json

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

编辑配置文件后，重新启动 Claude Desktop。

Cursor

将以下内容添加到你的 Cursor MCP 设置中（项目中的 .cursor/mcp.json 或全局设置）：

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

Codex

将以下内容添加到 .codex/config.toml：

[mcp_servers.python-docs]
command = "uvx"
args = ["python-docs-mcp-server"]

质量检查

• CI 会在 macOS 和 Linux 上，使用 Python 3.12 和 3.13 运行 ruff、pyright 和 pytest
• 基于子进程的 stdio 和冒烟测试会覆盖 MCP 协议管道
• 打包测试会检查 wheel 内容和 CLI 入口点
• 检索回归测试会覆盖精确符号匹配、版本行为、缺失符号、截断和本地版本默认值
• 手动 MCP QA 流程见 .github/INTEGRATION-TEST.md，使用 MCP Inspector 执行本地检查，并使用 Claude/Cursor 执行真实客户端检查

贡献者命令和验证步骤见 CONTRIBUTING.md。

工具

该服务目前提供七个 MCP 工具：

工具	描述
search_docs	按查询搜索 Python 标准库文档。支持符号查找（asyncio.TaskGroup）、模块搜索（json）和自由文本搜索。返回按 BM25 评分排序的结果及摘要摘录。
get_docs	按 slug 和可选锚点检索特定文档页面或章节。返回受预算限制并经过截断和分页的 Markdown 内容。检索结果会根据 Python 文档版本和请求标识缓存在磁盘上。
lookup_package_docs	查询 PyPI 官方软件包元数据，并返回软件包声明的文档、主页和源代码 URL。这是受控的 PyPI 元数据查询，不是通用网页搜索。
list_versions	列出所有已索引的 Python 版本及其元数据。
detect_python_version	检测用户本地的 Python 版本，并报告该版本是否已编入索引。
compare_versions	对比两个已编入索引的版本之间的 Python 标准库符号差异。返回 `change=added
whatsnew_for_version	浏览一个 Python 版本已编入索引的官方 What's New 页面中的非空章节。可选的 kind 用于按保守的标题层级类别筛选。start_index 和 max_sections 可对筛选结果分页；结构化响应上限为 20,000 个字符，截断的摘录会包含稳定锚点和后续调用 get_docs 的提示。规范标题和锚点保持不变；如果某个章节连同其元数据、非空索引文本及任何必要的续读提示都无法放入上限内，则会返回明确且有界的错误。页面大小可能会缩小，以确保摘录仍有可用内容。上限按模型 JSON 中的 Unicode 字符计数，不包括 MCP 信封。查询过程离线。

对于 kind="auto" 且显式指定了已编入索引的 version 的 search_docs，会先执行原有查找和全文搜索。如果两者都没有结果，服务会在提示词中查找带点号的 Python 标识符。该版本中恰好有一个已注册的不同标识符时，会启用符号查找回退；重复提及只计一次，未知标识符不计入。存在多个已知标识符时，结果为空。结果说明会标明回退匹配；这些匹配属于符号文档，并非对完整提示词的回答。显式指定的类型、未指定版本的搜索、非空结果和结果预算均保持不变。

为什么不使用 Context7 或通用文档检索？

如果你需要精确检索本地 Python 文档，而非广泛的网页搜索，请使用此服务：

• 使用 Python 官方文档，而非抓取的镜像或摘要
• 从 objects.inv 精确解析符号
• 支持 Python 3.10 至 3.14 的版本感知结果
• 检索章节，而非转储完整页面
• 通过 lookup_package_docs 获取 PyPI 声明的文档、主页和源代码链接
• 本地只读运行，无需 API 密钥

对于第三方库、任意网页或框架研究，请使用 Context7 或通用文档抓取工具。此服务并非通用文档搜索引擎，而是面向 AI 编码 Agent 的专用标准库检索工具。

已检索文档缓存

get_docs 响应会在 MCP 客户端或服务重启后，继续缓存在平台缓存目录中：

<platform cache dir>/mcp-python-docs/retrieved-docs-cache.sqlite3

缓存会保存已完成的 get_docs 结果，缓存键由解析后的 Python 文档版本和请求标识（slug、可选的 anchor、max_chars 和 start_index）组成。缓存未命中时，会使用常规的本地索引检索路径，然后写入结果。

缓存条目还会关联到本地 index.db 文件的指纹（路径、大小和修改时间戳）。如果重建或替换本地文档索引，旧条目会自动忽略。可以安全地删除 retrieved-docs-cache.sqlite3；这会移除缓存的检索结果，而不是文档索引。

PyPI 软件包文档查询

lookup_package_docs 会查询官方 PyPI JSON API，其文档位于 https://docs.pypi.org/api/json/（GET /pypi/<project>/json），并且只返回该软件包 PyPI 元数据中声明的来源：PyPI 项目 URL、 docs_url、home_page，以及允许列表中的 project_urls 标签，例如 Documentation、Homepage、Source 和 Repository。

该工具通过 trust_boundary="pypi-declared-metadata" 明确标示信任边界。它不会抓取网页、执行网页搜索，也不会悄悄回退到非官方的社区镜像。

诊断

检查本地环境：

uvx python-docs-mcp-server doctor

此命令会检查运行时 Python 版本、SQLite FTS5、缓存和索引路径、磁盘空间，以及 build-index 所需的 venv/ensurepip 支持。

验证现有索引：

uvx python-docs-mcp-server validate-corpus

故障排除

FTS5 不可用

如果你的 Python 构建不包含 SQLite FTS5：

Linux x86-64

Linux x86-64 用户可以安装可选的内置 SQLite 软件包：

pip install 'python-docs-mcp-server[pysqlite3]'

macOS / Windows / Linux ARM

从 python.org 安装 Python，或使用：

uv python install

Debian/Ubuntu 缺少 pythonX.Y-venv

如果 doctor 提示构建 venv 支持不可用，请安装与运行服务的 Python 次版本相同的 venv 软件包：

sudo apt install python3.12-venv

请将 3.12 调整为 doctor 显示的版本。如果没有此软件包， build-index 就无法创建用于构建 JSON 文档内容的一次性 Sphinx 环境。

从重命名前的 CLI 迁移

本项目早期开发快照使用的 PyPI 名称是 mcp-server-python-docs。已发布的 PyPI 项目名称是 python-docs-mcp-server。如果你的 MCP 客户端配置仍通过 uvx 引用旧名称， 就会看到 Package not found 错误，因为 uvx 根据 PyPI 名称解析项目。

将配置中的 args 从：

"args": ["mcp-server-python-docs"]

改为：

"args": ["python-docs-mcp-server"]

对于已经安装该软件包并通过 $PATH 按名称调用二进制文件的用户，wheel 仍会安装旧版 mcp-server-python-docs 控制台脚本。该脚本是一个别名，将在未来版本中移除。

uvx 缓存过期

如果 uvx python-docs-mcp-server 运行的是旧版本：

uvx --reinstall python-docs-mcp-server

或者清除 uv 缓存：

uv cache clean python-docs-mcp-server

Windows 上的 Claude Desktop（MSIX）

Windows 上以 MSIX 打包的 Claude Desktop 可能无法访问受限的 PATH。如果找不到 uvx，请在配置中指定完整路径：

{
  "mcpServers": {
    "python-docs": {
      "command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
      "args": ["python-docs-mcp-server"]
    }
  }
}

将 YOU 替换为你的 Windows 用户名。使用 where uvx 查找确切路径。

重建后重启

运行 build-index 后，请重启 MCP 客户端，使其加载新的数据库文件。服务会在启动时以只读方式打开索引，运行期间不会重新加载。

在 Windows 上，如果索引文件被锁定，请在重建前关闭 MCP 客户端。

贡献者工作流

有关贡献者设置和验证，请参阅：

• CONTRIBUTING.md
• .github/INTEGRATION-TEST.md
• .github/RELEASE.md

支持

已在 macOS 和 Linux 上测试。Windows 应该也能运行，但并未在每个版本中验证。

运行该服务需要 Python 3.12+。源码锁定的文档目标覆盖 Python 3.10 至 3.15；Python 3.15 需选择启用。可供查询的版本取决于构建索引时选择的文档版本。

许可证

MIT