{
  "markdown": "# python-docs-mcp-server\n\n<!-- mcp-name: io.github.ayhammouda/python-docs-mcp-server -->\n\n**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.**\n\n[![CI](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/ci.yml)\n[![Security Audit](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/security.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/security.yml)\n[![CodeQL](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml/badge.svg)](https://github.com/ayhammouda/python-docs-mcp-server/actions/workflows/codeql.yml)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ayhammouda/python-docs-mcp-server/badge)](https://scorecard.dev/viewer/?uri=github.com/ayhammouda/python-docs-mcp-server)\n[![python-docs-mcp-server MCP server](https://glama.ai/mcp/servers/ayhammouda/python-docs-mcp-server/badges/score.svg)](https://glama.ai/mcp/servers/ayhammouda/python-docs-mcp-server)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-latest-0f766e)](https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.ayhammouda%2Fpython-docs-mcp-server)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)\n[![No API Keys](https://img.shields.io/badge/API%20keys-none-success)](#why-use-it)\n[![Official Python Docs](https://img.shields.io/badge/source-official%20python%20docs-informational)](https://docs.python.org/3/)\n\nBuilt 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.\n\n## Why this exists\n\nThere is a difference between long context and usable context. Research like the\n[*Lost in the Middle*](https://arxiv.org/abs/2307.03172) study (Liu et al., 2023)\nfound that models struggle to use relevant information buried in the middle of a\nlong input. Pasting an entire documentation page into the model invites that\nfailure. Returning the exact symbol, section, and version keeps the answer in a\nshort, high-signal context instead.\n\nGeneric docs retrieval is a rough fit for Python stdlib questions:\n\n- `asyncio.TaskGroup` should resolve to the actual symbol, not a fuzzy page hit\n- Python version matters (`3.12` and `3.13` do not always say the same thing)\n- fetching a whole page burns tokens when one section answers the question\n- the official docs are canonical, but they do not ship as an MCP server\n\nThis server indexes the official docs locally and exposes a small set of MCP\ntools for lookup and section retrieval.\n\n## Why use it\n\n- no API keys to manage\n- queries run against a local index, not a hosted docs API\n- results come from the official Python docs\n- the server is read-only at runtime\n- fewer dependencies to review in strict environments\n\n## What you get\n\n- symbol lookup through Python `objects.inv`\n- page and section retrieval with truncation and pagination\n- a local SQLite + FTS5 index; no runtime web scraping\n- results for each Python version you index\n- six read-only MCP tools\n\n## Quick example\n\n**Prompt**\n\n> What does `asyncio.TaskGroup` do in Python 3.13?\n\n**Typical flow**\n\n1. `search_docs(\"asyncio.TaskGroup\", kind=\"symbol\", version=\"3.13\")`\n2. Call `get_docs(...)` using the slug and anchor returned by the best hit\n\n**Result**\n\nThe model gets the matching symbol and the relevant docs section, not a\nfull-page dump.\n\n## 30-second demo\n\nAsk your MCP client:\n\n> In Python 3.13, how should I use `asyncio.TaskGroup` and what changed from older asyncio patterns?\n\nIf setup is working, the client should use `search_docs` for the exact symbol,\nthen `get_docs` for the matching section. Instead of generic web results or an\nentire docs page, it gets official stdlib text for the requested Python version,\ntrimmed to the section that matters.\n\n## Install\n\nRun directly with `uvx`:\n\n```bash\nuvx python-docs-mcp-server --version\n```\n\nOr install it once with `pipx`:\n\n```bash\npipx install python-docs-mcp-server\n```\n\n---\n\nIf `uv` is installed but the `uv` command is not on your `PATH`, reopen your\nshell or use `python -m uv ...` as a fallback for local contributor commands.\n\n## First run\n\nBuild the local documentation index:\n\n```bash\nuvx python-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14\n```\n\nIf you installed the package persistently, you can drop the `uvx` prefix:\n\n```bash\npython-docs-mcp-server build-index --versions 3.10,3.11,3.12,3.13,3.14\n```\n\nThe first build downloads Python's `objects.inv` files, clones CPython docs\nsources, runs `sphinx-build -b json`, and writes an SQLite index to your local\ncache. It can take several minutes.\n\n## Configure your MCP client\n\n### Claude Code\n\nThis repository includes a project-scoped `.mcp.json` for clients that support\nchecked-in MCP server configuration. It points at the published package:\n\n```json\n{\n  \"mcpServers\": {\n    \"python-docs\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"python-docs-mcp-server\"]\n    }\n  }\n}\n```\n\nBuild the local documentation index with the first-run command above before\nexpecting docs queries to return corpus-backed results.\n\n### Claude Desktop\n\nAdd this to your Claude Desktop configuration file:\n\n**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n**Linux:** `~/.config/Claude/claude_desktop_config.json`\n\n**Windows:** `%APPDATA%\\\\Claude\\\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"python-docs\": {\n      \"command\": \"uvx\",\n      \"args\": [\"python-docs-mcp-server\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop after editing the config file.\n\n### Cursor\n\nAdd this to your Cursor MCP settings (`.cursor/mcp.json` in your project or\nglobal settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"python-docs\": {\n      \"command\": \"uvx\",\n      \"args\": [\"python-docs-mcp-server\"]\n    }\n  }\n}\n```\n\n### Codex\n\nAdd this to `.codex/config.toml`:\n\n```toml\n[mcp_servers.python-docs]\ncommand = \"uvx\"\nargs = [\"python-docs-mcp-server\"]\n```\n\n## Quality checks\n\n- CI runs `ruff`, `pyright`, and `pytest` on macOS and Linux for Python 3.12\n  and 3.13\n- subprocess-based stdio and smoke tests cover the MCP protocol pipe\n- packaging tests check the wheel contents and CLI entry points\n- retrieval regression tests cover exact symbol hits, version behavior,\n  missing symbols, truncation, and local-version defaults\n- manual MCP QA lives in\n  [`.github/INTEGRATION-TEST.md`](.github/INTEGRATION-TEST.md), with MCP\n  Inspector for local checks and Claude/Cursor for real-client checks\n\nContributor commands and validation steps live in\n[`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n## Tools\n\nThe server currently exposes six MCP tools:\n\n| Tool | Description |\n|------|-------------|\n| `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. |\n| `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. |\n| `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. |\n| `list_versions` | List all indexed Python versions with metadata. |\n| `detect_python_version` | Detect the user's local Python version and report whether that version has been indexed. |\n| `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. |\n\n## Why not Context7 or generic docs retrieval?\n\nUse this server when you want precise local Python docs retrieval rather than\nbroad web search:\n\n- official Python docs, not scraped mirrors or summaries\n- exact symbol resolution from `objects.inv`\n- version-aware results for Python 3.10 through 3.14\n- section retrieval instead of full-page dumps\n- PyPI-declared docs, homepage, and source links through `lookup_package_docs`\n- local read-only runtime with no API keys\n\nUse Context7 or a generic docs fetcher for third-party libraries, arbitrary web\npages, or framework research. This server is not a universal docs search engine;\nit is a focused stdlib retrieval tool for AI coding agents.\n\n## Retrieved docs cache\n\n`get_docs` responses are cached across MCP client/server restarts in the\nplatform cache directory:\n\n```text\n<platform cache dir>/mcp-python-docs/retrieved-docs-cache.sqlite3\n```\n\nThe cache stores completed `get_docs` results for the resolved Python docs\nversion plus request identity (`slug`, optional `anchor`, `max_chars`, and\n`start_index`). Cache misses use the normal local index retrieval path and then\nwrite the result.\n\nCache entries are also scoped to a fingerprint of the local `index.db` file\n(path, size, and modification timestamp). If you rebuild or replace the local\ndocs index, older entries are ignored automatically. Deleting\n`retrieved-docs-cache.sqlite3` is safe; it removes cached retrieval results, not\nthe docs index.\n\n## PyPI package docs lookup\n\n`lookup_package_docs` queries the official PyPI JSON API documented at\n`https://docs.pypi.org/api/json/` (`GET /pypi/<project>/json`) and returns only\nsources declared in that package's PyPI metadata: the PyPI project URL,\n`docs_url`, `home_page`, and allowlisted `project_urls` labels such as\nDocumentation, Homepage, Source, and Repository.\n\nThe tool makes the trust boundary explicit with\n`trust_boundary=\"pypi-declared-metadata\"`. It does not crawl pages, perform web\nsearch, or silently fall back to unofficial community mirrors.\n\n## Diagnostics\n\nCheck the local environment:\n\n```bash\nuvx python-docs-mcp-server doctor\n```\n\nThis checks the runtime Python version, SQLite FTS5, cache/index paths, disk\nspace, and the `venv`/`ensurepip` support needed by `build-index`.\n\nValidate an existing index:\n\n```bash\nuvx python-docs-mcp-server validate-corpus\n```\n\n## Troubleshooting\n\n### FTS5 unavailable\n\nIf your Python build does not include SQLite FTS5:\n\n**Linux x86-64**\n\nLinux x86-64 users can install the optional bundled SQLite package:\n\n```bash\npip install 'python-docs-mcp-server[pysqlite3]'\n```\n\n**macOS / Windows / Linux ARM**\n\nInstall Python from [python.org](https://www.python.org/) or use:\n\n```bash\nuv python install\n```\n\n### Missing `pythonX.Y-venv` on Debian/Ubuntu\n\nIf `doctor` says build venv support is unavailable, install the venv package\nfor the same Python minor version that runs the server:\n\n```bash\nsudo apt install python3.12-venv\n```\n\nAdjust `3.12` to match the version shown by `doctor`. Without this package,\n`build-index` cannot create the disposable Sphinx environment it uses to build\nJSON documentation content.\n\n### Migrating from the pre-rename CLI\n\nEarlier development snapshots of this project used the PyPI name\n`mcp-server-python-docs`. The published PyPI project is\n`python-docs-mcp-server`. If your MCP client config still references\nthe old name via `uvx`, you will see a `Package not found` error,\nbecause `uvx` resolves projects by PyPI name.\n\nChange your config `args` from:\n\n```json\n\"args\": [\"mcp-server-python-docs\"]\n```\n\nto:\n\n```json\n\"args\": [\"python-docs-mcp-server\"]\n```\n\nThe wheel still installs a legacy `mcp-server-python-docs` console\nscript for users who already have the package installed and invoke\nthe binary by name on `$PATH`. That script is an alias and will be\nremoved in a future release.\n\n### `uvx` cache stale\n\nIf `uvx python-docs-mcp-server` runs an old version:\n\n```bash\nuvx --reinstall python-docs-mcp-server\n```\n\nOr clear the uv cache:\n\n```bash\nuv cache clean python-docs-mcp-server\n```\n\n### Claude Desktop on Windows (MSIX)\n\nThe MSIX-packaged version of Claude Desktop on Windows may have restricted PATH\naccess. If `uvx` is not found, specify the full path in your config:\n\n```json\n{\n  \"mcpServers\": {\n    \"python-docs\": {\n      \"command\": \"C:\\\\Users\\\\YOU\\\\.local\\\\bin\\\\uvx.exe\",\n      \"args\": [\"python-docs-mcp-server\"]\n    }\n  }\n}\n```\n\nReplace `YOU` with your Windows username. Find the exact path with `where uvx`.\n\n### Restart after rebuild\n\nAfter running `build-index`, restart your MCP client so it picks up the new\ndatabase file. The server opens the index read-only on startup and does not\nreload it while running.\n\nOn Windows, close the MCP client before rebuilding if the index file is locked.\n\n## Contributor workflow\n\nFor contributor setup and verification:\n\n- [`CONTRIBUTING.md`](CONTRIBUTING.md)\n- [`.github/INTEGRATION-TEST.md`](.github/INTEGRATION-TEST.md)\n- [`.github/RELEASE.md`](.github/RELEASE.md)\n\n## Support\n\nTested on macOS and Linux. Windows should work, but it is not verified on\nevery release.\n\nThe server requires Python 3.12+ to run. Its generated documentation corpus\ncovers Python documentation versions 3.10 through 3.14.\n\n## License\n\nMIT\n",
  "bytes": 13626,
  "sha": "3216364282e11d78233436752faca16610a96305f94dd7a223696f6702e40a8f",
  "repo_slug": "ayhammouda/python-docs-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ayhammouda_python_docs_mcp_ser_4ae1e7aa/readme"
}