Python Docs MCP Server

python-docs-mcp-server

Python を記述する AI コーディングエージェントのための python-docs-mcp-server は、Python 標準ライブラリの信頼できる情報源です。正確なシンボル、正確なセクション、正確なバージョンを、オフラインで、常に無料、常に MIT ライセンスで、トークンを節約しながら提供します。

エージェントが asyncio.TaskGroup のシグネチャや pathlib.Path の仕様、あるいは 3.12 での変更点を必要とする場面のために作られています。ウェブからの取得でも、ホスト型 API でも、セクションアンカーをでっち上げるベクトルストアでもありません。実際に利用するバージョンに絞った docs.python.org のインデックスを、シンボルまたはクエリで返します。

このサーバーが作られた理由

長いコンテキストと、使えるコンテキストには違いがあります。 Lost in the Middle の研究（Liu ら、2023 年）では、長い入力の途中に埋もれた関連情報をモデルが活用するのは難しいことが示されています。ドキュメントページ全体をモデルに貼り付けると、その問題が起こりやすくなります。正確なシンボル、セクション、バージョンを返すことで、回答に必要な情報を短く、重要度の高いコンテキストに収められます。

一般的なドキュメント検索は、Python 標準ライブラリに関する質問にはあまり適していません。

• asyncio.TaskGroup は曖昧なページ検索結果ではなく、実際のシンボルに解決されるべきです
• Python のバージョンは重要です（3.12 と 3.13 で内容が異なる場合があります）
• 1 つのセクションで質問に答えられるのに、ページ全体を取得するとトークンを浪費します
• 公式ドキュメントが正準の情報源ですが、MCP サーバーとしては提供されていません

このサーバーは公式ドキュメントをローカルにインデックス化し、検索とセクション取得のための少数の MCP ツールを提供します。

利用する理由

• 管理が必要な API キーがありません
• クエリはホスト型ドキュメント API ではなく、ローカルインデックスに対して実行されます
• 結果は公式 Python ドキュメントから取得されます
• 実行時は読み取り専用です
• 厳格な環境で確認が必要な依存関係が少なくなります

提供内容

• Python objects.inv によるシンボル検索
• 切り詰めとページネーションに対応したページおよびセクションの取得
• ローカルの SQLite + FTS5 インデックス。実行時のウェブスクレイピングはありません
• インデックス化した各 Python バージョンの結果
• 7 つの読み取り専用 MCP ツール

簡単な例

プロンプト

Python 3.13 では asyncio.TaskGroup は何をしますか？

一般的な流れ

1. search_docs("asyncio.TaskGroup", kind="symbol", version="3.13")
2. 最適な検索結果から返されたスラッグとアンカーを使って 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にない場合は、シェルを再起動するか、ローカルのコントリビューター向けコマンドでは代わりにpython -m uv ...を使用してください。

検索結果の動作

明示的なバージョンを指定したkind="auto"では、検索結果が空でなく、結果枠に空きがある場合、プロンプトにそのバージョンの既知の修飾付き識別子が1つ含まれていれば、正確に一致するインベントリの対象を1つ追加することがあります。元のヒット、スニペット、スコア、順序、注記は保持されます。完全な結果、曖昧な識別子、その他の種類、バージョンを指定しないクエリには変更はありません。既存の空の検索結果に対するフォールバックにも変更はありません。インベントリのエイリアスも含め、正規化された場所は重複排除されます。

追加が許可されるのは、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.14と一緒に3.15もインデックス化するには、次を明示的に実行してください。

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

ビルドすると、ローカルインデックスは指定したバージョンで置き換えられるため、維持したいバージョンをすべて含めてください。上記の初回実行の例は、意図的に変更していません。ビルダーは引き続き、指定したバージョンのうち最も新しいものをインデックスのデフォルトに設定します。この対象を追加しても、既存のインデックスで3.15が選択されることはありません。バージョンを指定しないget_docsは、設定または検出されたデフォルトを使用します。一方、バージョンを指定しない検索は、インデックス化されたバージョン全体を対象にします。3.15だけの回答を得るには、version="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サーバー設定に対応するクライアント向けに、プロジェクト単位の.mcp.jsonが含まれています。公開済みのパッケージを参照します。

{
  "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 では Python 3.12 および 3.13 を対象に、macOS と Linux で ruff、pyright、pytest を実行します
• サブプロセスベースの stdio テストとスモークテストで、MCP プロトコルのパイプを検証します
• パッケージングテストで、wheel の内容と CLI エントリーポイントを確認します
• 検索回帰テストでは、シンボルの完全一致、バージョンの動作、シンボルが見つからない場合、切り捨て、ローカルバージョンの既定値を検証します
• 手動の MCP QA 手順は .github/INTEGRATION-TEST.md に記載されています。ローカルチェックには MCP Inspector を、実際のクライアントでのチェックには Claude/Cursor を使用します

コントリビューター向けのコマンドと検証手順は CONTRIBUTING.md に記載されています。

ツール

このサーバーでは現在、7 つの MCP ツールを提供しています。

ツール	説明
search_docs	クエリで Python 標準ライブラリのドキュメントを検索します。シンボル検索（asyncio.TaskGroup）、モジュール検索（json）、フリーテキスト検索に対応しています。BM25 スコアリングによる順位付け済みの検索結果と、抜粋を返します。
get_docs	スラッグと任意のアンカーを指定して、特定のドキュメントページまたはセクションを取得します。予算に応じた切り捨てとページネーションを適用した Markdown コンテンツを返します。取得結果は、Python ドキュメントのバージョンとリクエストの識別情報に基づいてディスクにキャッシュされます。
lookup_package_docs	PyPI の公式パッケージメタデータを調べ、パッケージが宣言するドキュメント、ホームページ、ソースの URL を返します。これは制御された PyPI メタデータ検索であり、汎用ウェブ検索ではありません。
list_versions	インデックス済みのすべての Python バージョンを、メタデータとともに一覧表示します。
detect_python_version	ユーザーのローカル Python バージョンを検出し、そのバージョンがインデックス化されているかどうかを報告します。
compare_versions	インデックス済みの 2 つのバージョン間で、Python 標準ライブラリのシンボルを差分比較します。`change=added
whatsnew_for_version	ある Python バージョンについて、インデックス済みの公式 What's New ページから空でないセクションを閲覧します。任意の kind を指定すると、保守的な見出し階層カテゴリで絞り込めます。start_index と max_sections で絞り込み結果をページ分割します。構造化レスポンスは 20,000 文字に制限され、切り捨てられた抜粋には安定したアンカーと get_docs での追加取得を促すヒントが含まれます。正式なタイトルとアンカーは変更されません。あるセクションのメタデータ、空でないインデックス済みテキスト、必要な継続ヒントを収められない場合は、明示的な上限付きエラーが返されます。使用可能な抜粋を確保するために、ページサイズを小さくする場合があります。上限の計算対象は、MCP エンベロープを除くモデル JSON 内の Unicode 文字です。クエリはオフラインで実行されます。

kind="auto" を指定した search_docs で、インデックス済みの version を明示した場合、最初に通常の検索と全文検索を実行します。どちらでも検索結果が得られなければ、サーバーはプロンプト内のドット区切りの Python 識別子を探します。そのバージョンに登録された異なる識別子がちょうど 1 つあれば、シンボル検索にフォールバックします。同じ識別子の繰り返しは 1 回として数え、未知の識別子は数えません。既知の識別子が複数ある場合、結果は空のままです。結果の注記にはフォールバックによる一致が示されます。これはシンボルのドキュメントであり、プロンプト全体への回答ではありません。明示的な kind、バージョンを指定しない検索、空でない検索結果、結果の予算には変更はありません。

Context7 や汎用ドキュメント検索ではなく、このツールを使う理由

幅広いウェブ検索ではなく、正確なローカル Python ドキュメント検索が必要な場合は、このサーバーを使用してください。

• スクレイピングされたミラーや要約ではなく、Python の公式ドキュメント
• objects.inv による正確なシンボル解決
• Python 3.10 から 3.14 までのバージョンを考慮した検索結果
• ページ全体のダンプではなく、セクション単位の取得
• lookup_package_docs による、PyPI が宣言するドキュメント、ホームページ、ソースへのリンク
• API キー不要の、読み取り専用ローカルランタイム

サードパーティライブラリ、任意のウェブページ、フレームワークの調査には、Context7 または汎用のドキュメント取得ツールを使用してください。このサーバーは万能なドキュメント検索エンジンではなく、AI コーディングエージェント向けに標準ライブラリの検索に特化したツールです。

取得済みドキュメントのキャッシュ

get_docs の応答は、MCP クライアント／サーバーの再起動後もプラットフォームのキャッシュディレクトリにキャッシュされます。

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

キャッシュには、解決済みの Python ドキュメントのバージョンとリクエストの識別情報（slug、省略可能な anchor、max_chars、start_index）に対応する、完了済みの get_docs の結果が保存されます。キャッシュミス時は通常のローカルインデックス取得パスを使用し、その後、結果を書き込みます。

キャッシュエントリは、ローカルの index.db ファイルのフィンガープリント（パス、サイズ、更新日時）にも紐づけられます。ローカルのドキュメントインデックスを再構築または置き換えると、古いエントリは自動的に無視されます。retrieved-docs-cache.sqlite3 を削除しても問題ありません。削除されるのはキャッシュされた取得結果であり、ドキュメントインデックスではありません。

PyPI パッケージのドキュメント検索

lookup_package_docs は、https://docs.pypi.org/api/json/ に記載されている公式 PyPI JSON API（GET /pypi/<project>/json）を照会し、そのパッケージの PyPI メタデータで宣言されたソースのみを返します。対象は、PyPI プロジェクト URL、docs_url、home_page、および Documentation、Homepage、Source、Repository などの許可リストに含まれる project_urls ラベルです。

このツールは、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 経由の古い名前が参照されたままだと、uvx は PyPI 名でプロジェクトを解決するため、Package not found エラーが発生します。

設定の args を次のように変更してください。

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

次のようにします。

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

wheel は、パッケージをすでにインストールしていて、$PATH 上のバイナリ名で実行するユーザー向けに、従来の 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