python-docs-mcp-server

python-docs-mcp-server

For AI coding agents writing Python, python-docs-mcp-server is the canonical Python stdlib oracle: exact symbols, exact sections, exact versions — offline, always free, always MIT, token-frugal.

Built for the moment your agent needs asyncio.TaskGroup signatures, pathlib.Path semantics, or what changed in 3.12 — not a web fetch, not a hosted API, not a vector store hallucinating section anchors. Just an indexed slice of docs.python.org, returned by symbol or by query, scoped to the version you actually ship on.

Why this exists

There is a difference between long context and usable context. Research like the Lost in the Middle study (Liu et al., 2023) found that models struggle to use relevant information buried in the middle of a long input. Pasting an entire documentation page into the model invites that failure. Returning the exact symbol, section, and version keeps the answer in a short, high-signal context instead.

Generic docs retrieval is a rough fit for Python stdlib questions:

• asyncio.TaskGroup should resolve to the actual symbol, not a fuzzy page hit

• Python version matters (3.12 and 3.13 do not always say the same thing)

• fetching a whole page burns tokens when one section answers the question

• the official docs are canonical, but they do not ship as an MCP server

This server indexes the official docs locally and exposes a small set of MCP tools for lookup and section retrieval.

Why use it

• no API keys to manage

• queries run against a local index, not a hosted docs API

• results come from the official Python docs

• the server is read-only at runtime

• fewer dependencies to review in strict environments

What you get

• symbol lookup through Python objects.inv

• page and section retrieval with truncation and pagination

• a local SQLite + FTS5 index; no runtime web scraping

• results for each Python version you index

• seven read-only MCP tools

Quick example

Prompt

What does asyncio.TaskGroup do in Python 3.13?

Typical flow

1. search_docs("asyncio.TaskGroup", kind="symbol", version="3.13")

2. Call get_docs(...) using the slug and anchor returned by the best hit

Result

The model gets the matching symbol and the relevant docs section, not a full-page dump.

30-second demo

Ask your MCP client:

In Python 3.13, how should I use asyncio.TaskGroup and what changed from older asyncio patterns?

If setup is working, the client should use search_docs for the exact symbol, then get_docs for the matching section. Instead of generic web results or an entire docs page, it gets official stdlib text for the requested Python version, trimmed to the section that matters.

Install

Run directly with uvx:

uvx python-docs-mcp-server --version

Or install it once with pipx:

pipx install python-docs-mcp-server

If uv is installed but the uv command is not on your PATH, reopen your shell or use python -m uv ... as a fallback for local contributor commands.

Search result behavior

For kind="auto" with an explicit version, a nonempty search with spare result slots may append one exact inventory target when the prompt contains one known qualified identifier in that version. Original hits, snippets, scores, order and notes are preserved. Full results, ambiguous identifiers, other kinds and versionless queries are unchanged; the existing empty-result fallback is unchanged. Canonical locations are deduplicated, including inventory aliases.

The append is admitted only when the complete proposed response serialized by Pydantic's compact model_dump_json() is at most 8000 UTF-8 bytes. This is not a global search cap: oversized original responses remain unchanged. It is separate from get_docs(max_chars=8000), which limits content characters.

First run

Build the local documentation index:

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

If you installed the package persistently, you can drop the uvx prefix:

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

The first build downloads Python's objects.inv files, clones CPython docs sources, runs sphinx-build -b json, and writes an SQLite index to your local cache. It can take several minutes.

Python 3.15 documentation (opt-in)

The source-pinned documentation targets include Python 3.10–3.15. To index 3.15 alongside 3.14, explicitly run:

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

A build replaces the local index with the requested versions; include every version you want to keep. The first-run examples above intentionally remain unchanged. The builder still marks the highest requested version as the index default; adding this target does not select 3.15 in an existing index. get_docs without a version uses the configured/detected default, while versionless search spans indexed versions. Pass version="3.15" for isolated 3.15 answers. list_versions reports the actual index, not all build targets; an unindexed explicit version raises an error, never an older-docs fallback.

This is documentation coverage, not a claim that the server runs on Python 3.15 or that a named MCP client was tested with it. Queries remain offline and read-only after a successful build. Until it is indexed, consult the official 3.15 docs directly.

The 3.15 target is CPython tag v3.15.0, commit d220409a13b77de7a6c30abe16ea90db01528edc, with Sphinx 8.2.3. See integration checks for explicit-version and comparison examples.

Configure your MCP client

Claude Code

This repository includes a project-scoped .mcp.json for clients that support checked-in MCP server configuration. It points at the published package:

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

Build the local documentation index with the first-run command above before expecting docs queries to return corpus-backed results.

Claude Desktop

Add this to your Claude Desktop configuration file:

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

Restart Claude Desktop after editing the config file.

Cursor

Add this to your Cursor MCP settings (.cursor/mcp.json in your project or global settings):

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

Codex

Add this to .codex/config.toml:

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

Quality checks

• CI runs ruff, pyright, and pytest on macOS and Linux for Python 3.12 and 3.13

• subprocess-based stdio and smoke tests cover the MCP protocol pipe

• packaging tests check the wheel contents and CLI entry points

• retrieval regression tests cover exact symbol hits, version behavior, missing symbols, truncation, and local-version defaults

• manual MCP QA lives in .github/INTEGRATION-TEST.md, with MCP Inspector for local checks and Claude/Cursor for real-client checks

Contributor commands and validation steps live in CONTRIBUTING.md.

Tools

The server currently exposes seven MCP tools: