Content
# python-docs-mcp-server
<!-- mcp-name: io.github.ayhammouda/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.**
[](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml)
[](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/security.yml)
[](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml)
[](https://scorecard.dev/viewer/?uri=github.com/ayhammouda/python-docs-mcp-server)
[](https://glama.ai/mcp/servers/ayhammouda/python-docs-mcp-server)
[](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.ayhammouda%2Fpython-docs-mcp-server)
[](LICENSE)
[](https://www.python.org/)
[](#why-use-it)
[](https://docs.python.org/3/)
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*](https://arxiv.org/abs/2307.03172) 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
- six 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`:
```bash
uvx python-docs-mcp-server --version
```
Or install it once with `pipx`:
```bash
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.
## First run
Build the local documentation index:
```bash
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:
```bash
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.
## 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:
```json
{
"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`
```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):
```json
{
"mcpServers": {
"python-docs": {
"command": "uvx",
"args": ["python-docs-mcp-server"]
}
}
}
```
### Codex
Add this to `.codex/config.toml`:
```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`](.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`](CONTRIBUTING.md).
## Tools
The server currently exposes six MCP tools:
| Tool | Description |
|------|-------------|
| `search_docs` | Search Python stdlib docs by query. Supports symbol lookup (`asyncio.TaskGroup`), module search (`json`), and free-text search. Returns ranked hits with BM25 scoring and snippet excerpts. |
| `get_docs` | Retrieve a specific documentation page or section by slug and optional anchor. Returns markdown content with budget-enforced truncation and pagination. Retrieved results are cached on disk by Python docs version and request identity. |
| `lookup_package_docs` | Look up official PyPI package metadata and return package-declared documentation/homepage/source URLs. This is a controlled PyPI metadata lookup, not generic web search. |
| `list_versions` | List all indexed Python versions with metadata. |
| `detect_python_version` | Detect the user's local Python version and report whether that version has been indexed. |
| `compare_versions` | Diff a Python stdlib symbol between two indexed versions. Returns `change=added|removed|changed|unchanged` with optional `new_in`, `changed_in`, `deprecated_in`, `signature_delta` (advisory heuristic), `see_also_added/removed`, `section_diff`, and `note` deltas. Token-frugal — emits only changed fields, not full content. |
## Why not Context7 or generic docs retrieval?
Use this server when you want precise local Python docs retrieval rather than
broad web search:
- official Python docs, not scraped mirrors or summaries
- exact symbol resolution from `objects.inv`
- version-aware results for Python 3.10 through 3.14
- section retrieval instead of full-page dumps
- PyPI-declared docs, homepage, and source links through `lookup_package_docs`
- local read-only runtime with no API keys
Use Context7 or a generic docs fetcher for third-party libraries, arbitrary web
pages, or framework research. This server is not a universal docs search engine;
it is a focused stdlib retrieval tool for AI coding agents.
## Retrieved docs cache
`get_docs` responses are cached across MCP client/server restarts in the
platform cache directory:
```text
<platform cache dir>/mcp-python-docs/retrieved-docs-cache.sqlite3
```
The cache stores completed `get_docs` results for the resolved Python docs
version plus request identity (`slug`, optional `anchor`, `max_chars`, and
`start_index`). Cache misses use the normal local index retrieval path and then
write the result.
Cache entries are also scoped to a fingerprint of the local `index.db` file
(path, size, and modification timestamp). If you rebuild or replace the local
docs index, older entries are ignored automatically. Deleting
`retrieved-docs-cache.sqlite3` is safe; it removes cached retrieval results, not
the docs index.
## PyPI package docs lookup
`lookup_package_docs` queries the official PyPI JSON API documented at
`https://docs.pypi.org/api/json/` (`GET /pypi/<project>/json`) and returns only
sources declared in that package's PyPI metadata: the PyPI project URL,
`docs_url`, `home_page`, and allowlisted `project_urls` labels such as
Documentation, Homepage, Source, and Repository.
The tool makes the trust boundary explicit with
`trust_boundary="pypi-declared-metadata"`. It does not crawl pages, perform web
search, or silently fall back to unofficial community mirrors.
## Diagnostics
Check the local environment:
```bash
uvx python-docs-mcp-server doctor
```
This checks the runtime Python version, SQLite FTS5, cache/index paths, disk
space, and the `venv`/`ensurepip` support needed by `build-index`.
Validate an existing index:
```bash
uvx python-docs-mcp-server validate-corpus
```
## Troubleshooting
### FTS5 unavailable
If your Python build does not include SQLite FTS5:
**Linux x86-64**
Linux x86-64 users can install the optional bundled SQLite package:
```bash
pip install 'python-docs-mcp-server[pysqlite3]'
```
**macOS / Windows / Linux ARM**
Install Python from [python.org](https://www.python.org/) or use:
```bash
uv python install
```
### Missing `pythonX.Y-venv` on Debian/Ubuntu
If `doctor` says build venv support is unavailable, install the venv package
for the same Python minor version that runs the server:
```bash
sudo apt install python3.12-venv
```
Adjust `3.12` to match the version shown by `doctor`. Without this package,
`build-index` cannot create the disposable Sphinx environment it uses to build
JSON documentation content.
### Migrating from the pre-rename CLI
Earlier development snapshots of this project used the PyPI name
`mcp-server-python-docs`. The published PyPI project is
`python-docs-mcp-server`. If your MCP client config still references
the old name via `uvx`, you will see a `Package not found` error,
because `uvx` resolves projects by PyPI name.
Change your config `args` from:
```json
"args": ["mcp-server-python-docs"]
```
to:
```json
"args": ["python-docs-mcp-server"]
```
The wheel still installs a legacy `mcp-server-python-docs` console
script for users who already have the package installed and invoke
the binary by name on `$PATH`. That script is an alias and will be
removed in a future release.
### `uvx` cache stale
If `uvx python-docs-mcp-server` runs an old version:
```bash
uvx --reinstall python-docs-mcp-server
```
Or clear the uv cache:
```bash
uv cache clean python-docs-mcp-server
```
### Claude Desktop on Windows (MSIX)
The MSIX-packaged version of Claude Desktop on Windows may have restricted PATH
access. If `uvx` is not found, specify the full path in your config:
```json
{
"mcpServers": {
"python-docs": {
"command": "C:\\Users\\YOU\\.local\\bin\\uvx.exe",
"args": ["python-docs-mcp-server"]
}
}
}
```
Replace `YOU` with your Windows username. Find the exact path with `where uvx`.
### Restart after rebuild
After running `build-index`, restart your MCP client so it picks up the new
database file. The server opens the index read-only on startup and does not
reload it while running.
On Windows, close the MCP client before rebuilding if the index file is locked.
## Contributor workflow
For contributor setup and verification:
- [`CONTRIBUTING.md`](CONTRIBUTING.md)
- [`.github/INTEGRATION-TEST.md`](.github/INTEGRATION-TEST.md)
- [`.github/RELEASE.md`](.github/RELEASE.md)
## Support
Tested on macOS and Linux. Windows should work, but it is not verified on
every release.
The server requires Python 3.12+ to run. Its generated documentation corpus
covers Python documentation versions 3.10 through 3.14.
## License
MIT
