gsearch

クイックスタート · 他との比較 · 取得できる内容 · 仕組み · プロキシ · パフォーマンス · FAQ

AI エージェント向けの本物の Google 検索。API キー不要。セルフホスト可能。MCP 経由。

エージェントが google_search を呼び出すと、Google の実際の検索結果ページが型付き JSON で返されます。すべてのリンクは実際の URL に解決され、Google の回答ボックス（スポーツの結果、トップニュース、動画）、AI Overview、「他の人はこちらも質問」、関連検索も含まれます。本物の Firefox （Camoufox）が Google のページをそのまま表示します。自分の IP、またはすでに利用している任意のプロキシを経由できます。

理由： 通常の HTTP では JavaScript の壁に阻まれ、自動操作の Chrome はテストで 2 回中 2 回 CAPTCHA が表示されました。また、Google の公式 Custom Search API は 2027 年 1 月 1 日に終了します。他の検索 MCP サーバーは、Google のインデックスではない（Brave、Tavily、Exa、DuckDuckGo）か、検索ごとに料金がかかります（SerpApi、Bright Data）。

_{セッションを確立した状態で、自宅の IP から実際にライブ呼び出しした結果を表示しています。表示されている待ち時間は実測値です。MP4}

🚀 クイックスタート

uv tool install gsearch-agent                         # or: pipx install gsearch-agent
gsearch setup                                         # downloads the browser once (~1 GB), prints your MCP config
claude mcp add gsearch --scope user -- gsearch-mcp    # or any MCP client, below

あとは、「asyncio とは何かを Google で検索して、上位 3 件のリンクを教えて」、「asyncio について他の人は何を質問していますか？」、「過去 1 年以内の python.org にある asyncio のページを探して」、*「asyncio のドキュメントを検索して、最初の結果を要約して」*と尋ねるだけです。

プロキシを使わない場合、gsearch は自分の IP を使い、検索回数は 1 時間あたり最大 20 回です。さらに検索するには、次のように任意の形式のプロキシを追加します。

claude mcp add gsearch --scope user -e GSEARCH_PROXY="gate.example.com:7000:user-sid-{sid}:password" -e GSEARCH_DATA_LIMIT_MB=1000 -- gsearch-mcp

{
  "mcpServers": {
    "gsearch": {
      "command": "gsearch-mcp",
      "env": { "GSEARCH_PROXY": "optional, any format", "GSEARCH_DATA_LIMIT_MB": "1000" }
    }
  }
}

メモ

Google 検索への自動アクセスは、Google の利用規約に違反する可能性があります。ライブ検索を実行する前に、法令遵守と責任ある利用をお読みください。

🆚 比較

_{「さまざま」：これらのプロジェクトはテストしていません。Chromium に関する唯一の測定結果は F-0001です。gsearch が配信された IP では、Playwright Chrome は 2 回中 2 回 CAPTCHA が表示されました。実際の検索を行う前に法的事項をお読みください。}

_{2026 年 10 月に測定： F-0014、 F-0006、 F-0011、 F-0012、 F-0001； クリーンなプロキシ IP で 14 秒、0.6 MB：F-0015。 フラグが付けられたプロキシプールでは、さらに時間がかかります：[パフォーマンス](#-performance)をご覧ください。}

✨ gsearch を選ぶ理由

Google の公式検索 API は新規顧客の受付を終了しており、2027 年 1 月 1 日にサービスを終了します （F-0005）。gsearch は AI エージェント向けに構築されています：

• 🦊 スクレイパーではなく、本物のブラウザー。 強化された Firefox である Camoufox が、実際のデバイスのフィンガープリントと IP に合ったロケールを使い、Google のページをそのまま表示します。
• 🔗 実際の URL。 Google は /goto リダイレクトの背後に検索結果のリンクを隠します。gsearch はリンク先のページを読み込まずに、すべてのリンクをそのページの URL に解決します。
• 🤖 エージェント向けに構築。 1 つの MCP サーバーで検索、ページの読み取り、ステータス確認を行い、型付き JSON を返します。ブロックは空の検索結果ではなく、retry_after_s を含む明確なエラーとして返され、すべての文字列には信頼できないウェブコンテンツであることを示すフラグが付きます。
• 🌍 あらゆるプロキシ、あらゆる形式。 ローテーション型の住宅用、静的 VPS、データセンターのリストに対応し、HTTP、HTTPS、SOCKS5 など一般的な形式を利用できます。すべてのバイト数を計測し、厳格なデータ上限を設けています。
• 🎯 調整不要。 設定は 2 つだけです。それ以外はすべて、テストで最良の結果が得られた設定に固定されています。
• 📊 正直な数値。 この README にあるすべての主張から、測定方法の記録を確認できます。

📦 エージェントが受け取るもの

保存された検索結果ページからの実際の出力です（オフラインデモモードでは url は null のままですが、ライブ検索では値が入力されます）。

ブロックされた場合に空のリストが返されることはありません。何が起きたのかと、どれくらい待つべきかを示すエラーが返されます。

🔍 仕組み

• 人間のように動作します。 プロキシIPではヘッドレスセッションがはるかに頻繁にブロックされたため、ウィンドウを表示します (F-0015)。クエリはアドレスバーに入力されます。 WebRTCは無効になっているため、プロキシを迂回して実際のIPが漏れることはありません。
• 偽装しません。 gsearchがGoogleのトークンを生成または変更することはありません。ブラウザーはページをそのまま実行します。
• リンクを安全に解決します。 同じIPと同じCookieを使い、ブラウザーに一致するTLSフィンガープリントでリンクを解決します (F-0011、 F-0013)。
• サーバーで動作します。 画面のないLinuxマシンでは、ブラウザーが仮想ディスプレイを自動的に使用します （sudo apt install xvfb）。

🌍 プロキシ

# rotating residential: {sid}, or your provider's sid-…, session-…, sessid-… part, gives a new IP per search
GSEARCH_PROXY=gate.example.com:7000:user-country-us-sid-{sid}:password

# static proxies (VPS, datacenter, ISP): one or many, separated by commas, spaces or new lines
GSEARCH_PROXY=socks5://user:[email protected]:1080, http://203.0.113.11:3128

# or a file with one proxy per line
GSEARCH_PROXY=/path/to/proxies.txt

• ローテーション式： 検索ごとに新しいIPと新しいブラウザーを使用し、同時に最大3件まで実行できます。ブロックされたIPは置き換えられ、検索1回あたり最大4個のIPを使用します。ログイン情報内の country-xx または cc-xx を確認し、指定地域以外の出口は除外します。
• 固定式： 各IPはセッションを温存しながら順番に使用されます。各IPには個別の利用上限（1時間あたり20回、1日あたり150回）があり、CAPTCHAが発生すると深夜まで休止します。そのため、IPが10個あれば1時間あたり約200回まで検索できます。
• データ： すべてのバイトは、通信量をカウントするローカルリレーを経由します。再起動後も適用される上限に達すると、GSEARCH_DATA_LIMIT_MB がすべての処理を停止します。

ヒント

プロキシプロバイダーの利用規約を確認してください。自動アクセスを禁止するサイトでのネットワーク利用や、CAPTCHAの解決を禁止しているプロバイダーも多くあります。

📊 パフォーマンス

プロキシの品質で速度とコストが決まります。 多くの住宅用 IP は、すでに Google にフラグを立てられています。フラグを立てられた IP を使うたびに、次の IP を試す前にブラウザーの起動コスト（約 0.7～1 MB、20 秒）が発生します。

プロキシを使わない場合、自分の IP でのウォームセッションは検索あたり約 1.2 秒で、テストではすべてのリンクが解決され、CAPTCHA は 0 件でした（F-0014）。ただし、IP を保護するため、1 時間あたり 20 回の検索に制限されます。静的プロキシはまだベンチマークされていません。

データ上限の範囲内で、ご自身のプロキシを測定してください。

python tools/benchmark.py -n 10

🛠 リファレンス

gsearch search "query" [--page N] [--lang xx] [--country xx] [--time-range h|d|w|m|y] [--site domain]
gsearch search "query" --fixtures fixtures/gecko     answer from saved pages (offline, from a clone of this repo)
gsearch fetch URL                                    readable text and links of a web page
gsearch parse page.html                              parse any saved Google results page
gsearch schema                                       print the JSON Schema
gsearch identity check                               home-IP browser's fingerprint matches its IP (no Google traffic)
gsearch setup                                        download the browser once and print the MCP config

import asyncio
from gsearch_core.client import SearchClient
from gsearch_core.config import fetcher_from_env
from gsearch_parse.models import SearchRequest

async def main() -> None:
    fetcher, _live = fetcher_from_env()      # reads the settings and .env
    result = await SearchClient(fetcher).search(SearchRequest(query="what is asyncio in python"))
    print(result.model_dump_json(indent=2))  # SearchResponse or SearchError
    await fetcher.aclose()

asyncio.run(main())

プロキシは必要ですか？ いいえ。プロキシを使わない場合、gsearch は自身の IP アドレスを使い、セッションを維持して検索します（検索あたり約 1.2 秒）。IP アドレスをクリーンに保つため、1 時間あたり 20 回、1 日あたり 150 回に制限されています。大量に検索する場合は、プロキシを使ってください。

どのプロキシを購入すればよいですか？ セッション維持機能付きのローテーション式住宅用プロキシ（ユーザー名にセッション ID を含めるもの）がおすすめです。価格より品質が重要です。追加購入する前に、小規模なプランで tools/benchmark.py を実行してください。

検索ではプロキシのデータをどのくらい使用しますか？ IP アドレスがクリーンな場合、約 0.6 MB です。問題のある IP アドレスでは、ブラウザーの起動が無駄になるため、使用量が増えます。使いすぎを防ぐため、GSEARCH_DATA_LIMIT_MB を設定してください。

CAPTCHA を解決できますか？ いいえ。ブロックされた IP アドレスは破棄され、新しい IP アドレスが試されます。gsearch に CAPTCHA ソルバーは含まれておらず、Google のトークンを偽造することもありません。

サーバー上で実行できますか？ はい。画面のない Linux では、Xvfb をインストールすると、ブラウザーが仮想ディスプレイ上で実行されます。

どのエージェントで使えますか？ Claude Code、Claude Desktop、Cursor など、あらゆる MCP クライアントで使えます。CLI を使ったり、Python から呼び出したりすることもできます。

📜 法令遵守と責任ある利用

• Google の利用規約では、Google 検索への自動アクセスが制限されています。 このツールを Google に対して実行すると、このプロジェクトのライセンスにかかわらず、利用規約に違反する可能性があります。
• 訴訟リスクは現実のものであり、現在も存在します。 Google v. SerpApi（カリフォルニア北部地区連邦地方裁判所、2025-12-19 提訴）で、Google は SearchGuard の JavaScript チャレンジを自動化された手段で解決することは、DMCA §1201 における回避行為にあたると主張しています。gsearch は実際のブラウザーでこのチャレンジを実行し、トークンを偽造または変更しませんが、訴状は自動化されたブラウザーも対象としています。詳しくは docs/DESIGN.md（D-004）をご覧ください。
• CAPTCHA ソルバーは同梱も組み込みも推奨もされていません。 CAPTCHA が表示されると、その検索は中断され、エラーとして報告されます。
• 実際の検索を実行する前に、お住まいの地域の法律と利用目的について、法律の専門家に相談してください。 パーサー（gsearch_parse）が読み取るのは、すでに手元にある HTML のみです。
• 制限はデフォルトで有効になっており、CLI や MCP から回避することはできません。 プロキシを使って Google に大量のリクエストを送らないでください。
• 個人データを収集しないでください。 人物のプロファイリング、人物検索結果のスクレイピング、個人データの大規模な収集は行わないでください。キャッシュの保存期間は短くし、未加工の検索結果を再公開しないでください。
• ブロックされた場合は、アクセスを控えてください。 CAPTCHA やレート制限は retry_after_s を含むエラーとして返されます。gsearch がチャレンジの回避を試みることはありません。

プロンプトインジェクション

検索結果に含まれるタイトル、スニペット、URL、質問はすべて、オープンウェブ上の信頼できない第三者のテキストであり、エージェントを狙った指示が含まれている可能性があります。ツールの説明にもその旨が記載されており、すべての応答に meta.untrusted_content: true と MCP の untrusted_content フラグが含まれ、テキストの要約の末尾にも警告が付加されます。検索結果は厳密にデータとして扱ってください。

🤝 貢献

テストが Google に接続することはありません。パーサーは保存済みのページで、ブラウザーはローカルの偽 Google 環境でテストされます。プルリクエストを歓迎します。初めて取り組むのに適した課題を選び、ロードマップを確認して、CONTRIBUTING.mdと docs/DESIGN.mdから始めてください。

gsearch で時間を節約できたら、⭐ を付けて他の人にも見つけてもらいましょう。

ライセンス

MIT。Camoufox（MPL-2.0）は依存関係として PyPI からインストールされ、ベンダー同梱されることはありません。