web-search-mcp

ローカルLLM向けの外部ウェブ検索およびページ取得機能。MCPツールおよびCLIとして公開されています。実装はPlaywrightファーストの非同期処理で、デフォルトでシステムにインストールされたChromiumバイナリを起動します。設計の経緯は docs/IMPLEMENTATION_PLAN.md に記載されています。

ツール

• search(provider, context) は、duckduckgo（デフォルト）、google、またはyandexでブラウザベースの検索を実行し、最大5件のオーガニック検索結果URLを返します。

• fetch(urls) は 1..5 件のURLを取得し、URLごとの pages、errors、truncated フィールドを含むブラウザレンダリング済みのHTMLを返します。

context は、呼び出し元との互換性を保つため、意図的に検索クエリ文字列としています。

Related MCP server: Web Search MCP

セットアップ

uv sync
chromium --version

Chromiumが標準以外の場所にインストールされている場合は、PLAYWRIGHT_CHROMIUM_EXECUTABLE=/path/to/chromium を設定してください。

使用方法

MCPサーバーをstdio経由で実行します：

uv run web-search serve-mcp

CLIを直接実行します：

uv run web-search search --context "python async playwright"
uv run web-search fetch https://example.com

stdioの代わりにHTTPトランスポートを公開します：

uv run web-search serve-mcp --transport streamable-http --host 127.0.0.1 --port 8000

設計上の注意点

• プロセスごとに1つの共有ブラウザを使用し、リクエストごとに新しいシークレットコンテキストを作成します。

• Playwrightは、Playwrightがダウンロードしたブラウザバンドルではなく、システムのChromiumバイナリを起動します。

• システムのChromiumはPlaywrightで動作しましたが、テストしたシステムのFirefoxビルドは起動直後に終了しました。そのため、このリポジトリではサポート対象のホストブラウザとしてシステムのChromiumをターゲットにしています。

• ブラウザの健全性テスト（スモークテスト）は、通常のホストシェルから実行する必要があります。制限されたサンドボックス環境では、ホストブラウザが正しく動作していてもChromiumの起動がブロックされる可能性があります。

• グローバルなナビゲーションの同時実行数は 3 に制限されています。

• タイムアウト：ページごとに 15s、search 全体で 20s、fetch 全体で 35s です。

• SSRF対策：http/https のみに限定し、埋め込み認証情報は使用せず、ナビゲーション前およびブラウザのサブリクエスト時にループバック/プライベート/リンクローカル/予約済みIPをブロックします。

• JavaScriptチャレンジページには 10s の待機ウィンドウが設定されています。CAPTCHAの解決、ステルスフィンガープリント、サイト固有のバイパスロジックはありません。

• HTMLはURLごとに 1 MiB に制限されています。サイズ超過のレスポンスは切り捨てられ、truncated に報告されます。

• v1では robots.txt は参照されません。

開発

source .venv/bin/activate
pytest

パーサーテストは保存されたHTMLフィクスチャに対して実行されます。セレクターのドリフトは、メンテナンスコストとして想定されています。