python-docs-mcp-server

python-docs-mcp-server is a read-only MCP (Model Context Protocol) server designed specifically for AI coding agents writing Python code, providing local, precise retrieval of the official Python standard library documentation. It is positioned as the "authoritative oracle for the Python standard library": exact symbols, exact sections, exact versions, available offline, always free, MIT licensed, and token-saving.

Purpose

This tool solves the common problems AI coding agents encounter when querying the Python standard library: general documentation retrieval tends to return vague page hits, while Python version differences (such as 3.12 versus 3.13) lead to different documentation content; directly scraping entire pages wastes tokens, and the official documentation itself is not provided in the form of an MCP server. python-docs-mcp-server indexes the official documentation locally and exposes lookup and section retrieval capabilities through a small set of MCP tools, letting agents obtain exact symbols, sections, and version information rather than full-page dumps or hallucinated anchors produced by vector stores.

Main capabilities

• Exact symbol lookup via Python's objects.inv.
• Supports page and section retrieval, with truncation and pagination.
• Uses a local SQLite + FTS5 index, with no network scraping required at runtime.
• Provides results for each indexed Python version, covering documentation versions from Python 3.10 to 3.14.
• Provides seven read-only MCP tools.
• No API keys to manage; queries run against the local index rather than a hosted documentation API.
• Results come from the official Python documentation, are read-only at runtime, and have few dependencies, making them easy to review in strict environments.
• Queries PyPI-declared documentation, homepage, and source links via lookup_package_docs.

Usage

How to run: you can run it directly with uvx, or install it once with pipx. If uv is installed but the uv command is not in PATH, reopen the shell or use python -m uv ... as a fallback for local contributor commands.

Building the local documentation index: the first build downloads Python's objects.inv file, clones the CPython documentation source, and runs sphinx-build -b json, and writes the SQLite index to the local cache. This process may take several minutes. If the package is already persistently installed, the uvx prefix can be removed.

Configure the MCP client: the repository contains a project-level .mcp.json, suitable for clients that support checked-in MCP server configuration, pointing to the published package. Before documentation queries are expected to return corpus-based results, the first build command must be run.

Claude Desktop configuration: add the configuration to the 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), and restart Claude Desktop after editing.

Cursor configuration: add to the Cursor MCP settings (.cursor/mcp.json in the project or global settings).

Codex configuration: add to .codex/config.toml.

Usage example: ask the MCP client, "In Python 3.13, how do you use asyncio.TaskGroup, and how does it differ from older asyncio patterns?" If the setup is working correctly, the client should use search_docs to find the exact symbol, then use get_docs to retrieve the matching section, thereby obtaining the official standard library text for the requested Python version, trimmed to the relevant section.

Search behavior: for the case where kind="auto" and an explicit version is specified, if a non-empty search has remaining result slots, when the prompt contains a known qualified identifier in that version, an exact manifest target may be appended. Original hits, snippets, scores, order, and annotations are all preserved. Full results, ambiguous identifiers, other kinds, and versionless queries remain unchanged; the existing empty-result fallback remains unchanged. Canonical locations are deduplicated, including manifest aliases. Appending is allowed only when the full proposed response, after Pydantic's compact model_dump_json() serialization, does not exceed 8000 UTF-8 bytes. This is not a global search limit: oversizedThe original response remains unchanged. This differs from get_docs(max_chars=8000), which limits the number of content characters.

For search_docs with kind="auto" and an explicit index version specified, the raw lookup and full-text search run first. If neither returns a hit, the server looks for dotted Python identifiers in the prompt. Exactly one distinct identifier registered in that version enables the symbol lookup fallback; repeated mentions count only once, and unknown identifiers do not count. Multiple known identifiers result in an empty result. Result annotations identify fallback matches, which are symbol documents rather than answers to the full prompt. Explicit kind, versionless search, non-empty results, and the result budget remain unchanged.

When to use

• When an AI coding agent needs to look up exact symbol signatures, semantics, or version changes in the Python standard library.
• When official documentation sections for a specific Python version (3.10 to 3.14) are needed rather than full-page content.
• When a read-only, no-API-key, low-dependency local documentation retrieval tool is needed in a strict environment.
• When the documentation, homepage, and source links declared by a PyPI package need to be looked up.

Limitations

• This server is not a general-purpose documentation search engine, but a tool focused on standard library retrieval. For third-party libraries, arbitrary web pages, or framework research, Context7 or a general-purpose documentation fetcher should be used.
• The server requires Python 3.12+ at runtime.
• The generated documentation corpus covers Python documentation versions 3.10 to 3.14.
• Building the index for the first time may take several minutes.
• Tested on macOS and Linux; Windows should work, but not every version has been verified.
• If the Python build does not include SQLite FTS5, additional handling is required.
• On Debian/Ubuntu, if pythonX.Y-venv is missing, build-index cannot create the one-off Sphinx environment used to build the JSON documentation content.
• When migrating from the old CLI, if the MCP client configuration still references the old PyPI name mcp-server-python-docs via uvx, a Package not found error will occur.
• After rebuilding the index, the MCP client must be restarted to load the new database file; the server opens the index read-only at startup and does not reload it during operation.Load. On Windows, if the index file is locked, the MCP client must be closed before rebuilding.
• The uvx cache may be stale, causing an old version to run.
• On Windows, the MSIX-packaged Claude Desktop may restrict PATH access; if uvx cannot be found, the full path must be specified in the configuration.

Other Information

Retrieved document cache: get_docs responses are cached across MCP client/server restarts in the platform cache directory. The cache stores completed get_docs results, keyed to the resolved Python documentation version and the request identity (slug, optional anchor, max_chars, and start_index). On a cache miss, the normal local index retrieval path is used, and then the result is written. Cache entries are also scoped to the fingerprint of the local index.db file (path, size, and modification timestamp). If the local documentation index is rebuilt or replaced, old entries are automatically ignored. Deleting retrieved-docs-cache.sqlite3 is safe; it removes cached retrieval results, not the documentation index.

PyPI package documentation lookup: lookup_package_docs queries the official PyPI JSON API (GET /pypi/<project>/json) and returns only the sources declared in that package's PyPI metadata: PyPI project URL, docs_url, home_page, and allowlisted project_urls labels such as Documentation, Homepage, Source, and Repository. The tool explicitly trusts the boundary via trust_boundary="pypi-declared-metadata". It does not scrape pages, does not perform web searches, and does not silently fall back to unofficial community mirrors.

Environment checks and index validation: The local environment can be checked (runtime Python version, SQLite FTS5, cache/index paths, disk space, and the venv/ensurepip support required by build-index), and an existing index can be validated.

Contributor workflow: CI runs ruff, pyright, and pytest on macOS and Linux against Python 3.12 and 3.13; subprocess-based stdio and smoke tests cover the MCP protocol pipeline; packaging tests check 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 is located in .github/INTEGRATION-TEST.md, using MCP Inspector for local checks and Claude/Cursor for real-client checks. Contributor commands and validation steps are located in CONTRIBUTING.md.