google-surf-mcp

✨アンチボット検索MCP：APIキー不要✨

English | 한국어

デモ用です。実際の検索はデフォルトでヘッドレス（ブラウザが表示されない状態）で実行されます。上のクリップのようにChromeを表示させるには SURF_HEADLESS=false を設定してください。

Google検索MCP。APIキー不要。そのまま使えます。

• ✅ 実際に動作します（6つの無料Google検索MCPをテストしましたが、すべて失敗しました）

• ✅ 検索とURL抽出を1つのMCPで実行（通常の検索MCP + 取得MCPの組み合わせを置き換えます）

• ✅ 4つのツール：search / search_parallel / extract / search_extract

• ✅ APIキー、プロキシ、ソルバー不要

• ✅ 自動CAPTCHA復旧（Chromeが開き、人間が一度解決すると呼び出しが再試行されます）

• ✅ extract におけるSSRFガード（デフォルトで localhost、プライベートIP、AWSメタデータをブロック）

概要

任意のMCPクライアントにプラグインするだけで、Google検索をツールとして利用できます。

CAPTCHAソルバーは不要です。いずれかのツールでCAPTCHAが発生すると、人間が解決するためのChromeウィンドウが開きます。解決するたびに、Googleに対するプロファイルの評価が維持されます。持続可能で倫理的な利用のために構築されています。

初回インストール時に約1秒のプロファイル準備が必要です（「インストール」を参照）。

ローカルでの使用を想定して設計されています。ステートレス/サーバーレス環境でのデプロイには適していません。

Related MCP server: Brave Search MCP Server

数値

1Gb/s接続のワークステーションで測定。

スタック

• Playwright + 永続的なChromeプロファイル

• playwright-extra ステルス機能

• 高速化のための画像/メディア/フォントのリソースブロック

• 初回実行前のワンショットプロファイルブートストラップ

• 記事抽出のためのMozilla Readability + Turndown

インストール

Node 18以上とGoogle Chrome（またはChromium）がシステムに必要です。

npx google-surf-mcp   # actual MCP - register in client config

またはローカルクローン：

git clone https://github.com/HarimxChoi/google-surf-mcp
cd google-surf-mcp
npm install
npm run bootstrap

bootstrap を実行するとChromeウィンドウが開きます。そこで一度Google検索を実行し、閉じてください。これでプロファイルの準備が完了します。

必要に応じてパスを上書きしてください：

CHROME_PATH=/path/to/chrome SURF_TZ=America/New_York npm run bootstrap

Claude Codeでの使用

~/.claude.json に以下を貼り付けます：

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"]
    }
  }
}

Claude Codeを再起動します。これで完了です。search、search_parallel、extract、search_extract が利用可能になります。

他のMCPクライアントの場合は、設定ファイルで同じJSON形式を使用してください。

ローカルクローン版：

{
  "mcpServers": {
    "google-surf": {
      "command": "node",
      "args": ["/abs/path/to/google-surf-mcp/build/index.js"]
    }
  }
}

ツール

• search(query, limit?) - 単一クエリ、約1.5秒。タイトル/URL/スニペットを返します。スポンサー広告は除外されます。

• search_parallel(queries[], limit?) - 4つのプール、1呼び出しあたり最大10クエリ。

• extract(url, max_chars?) - URLを取得し、記事のマークダウンを返します（Readabilityを使用し、テキストフォールバックあり）。失敗時は { error } を返し、例外は投げません。

• search_extract(query, limit?, max_chars?) - 検索 + 並列抽出を1回の呼び出しで実行。記事全文の内容で強化されたSERP結果を返します。ページごとの失敗は分離されます。

search_extract が最も強力です：SERPと記事全文の内容を1回の呼び出しで取得します。多くのエージェントが組み合わせている「検索MCP + URL取得MCP」の組み合わせを置き換えます。

環境変数

トラブルシューティング

• CAPTCHA: 可視状態のChromeウィンドウが自動的に開きます（4つのツールすべてで動作）。一度解決して検索を実行すれば、呼び出しが再試行され継続します。失敗時に即座に終了させたい場合は、ディスプレイなしで実行してください。

• "Chrome not found": Chromeをインストールするか、CHROME_PATH を設定してください。

• Stale selectors: Googleはクラス名を変更することがあります。プルリクエストを歓迎します。

変更履歴

CHANGELOG.md を参照してください。

ライセンス

MIT