AIエージェントとScrapeless MCPサーバーを使用して、大規模にGoogleマップをスクレイピングする方法

主なポイント：

• MCPをサポートするクライアントで動作します。 Scrapeless MCP Server は、クラウドブラウザを一連の Model Context Protocol ツール — Claude Desktop、Claude Code、Cursor、OpenAI Codex CLI、Gemini CLI、VS Code + GitHub Copilot Chat、または MCP TypeScript SDK に対して構築されたカスタムクライアント — として提供します。プロトコルが支えになっているのであって、クライアントではありません。SDKのグルーも、CLIのサブプロセス管理も不要です。
• ブラウザのプリミティブはGoogleマップのスクレイパーに組み合わさります。 サーバーは、汎用のブラウザツール — browser_create、browser_goto、browser_wait_for、browser_get_html、browser_get_text、browser_click、browser_type、browser_press_key、browser_scroll、browser_scroll_to、browser_screenshot、browser_snapshot、browser_close — を提供し、エージェントはそれらを検索 → スクロール → 抽出の流れに組み立てます。これはGoogleマップで求められています。
• 2つの輸送モード。 Stdioモードは、npx scrapeless-mcp-serverを介してローカルでサーバーを実行し、ワークステーション上のデスクトップMCPクライアントに適したデフォルトです。HTTPストリーミングモードは、クライアントを https://api.scrapeless.com/mcp にポイントし、クラウドホストされたエージェントに適したデフォルトです。
• クラウドレンダリングとレジデンシャルプロキシ。 GoogleマップはJavaScriptが重いSPAで、結果をフィードとしてレイジーロードします。Scrapeless Scraping Browserは、JSレンダリング、レジデンシャルプロキシの出口、各セッションでの検出回避フィンガープリンティングを処理します — エージェントはページを操作するだけで済みます。セッションは、Scrapelessアカウントが設定されているプロキシリージョンを介して割り当てられます。MCPツール表面を通じて、呼び出しごとのリージョンのオーバーライドは公開されていません。
• クエリごとの結果リストの上限。 Googleマップは、サイドフィードに対して1クエリあたり最大120の結果を表示します。それを超える場合、戦略は地理的グリッドです：検索エリアを小さなバウンディングボックスに分割し、タイルごとに1件のクエリを実行し、場所IDで重複を排除します。
• 無料で始められます。 新しいScrapelessアカウントには、無料のScraping Browserランタイムが含まれています — Scrapelessでサインアップしてください。

はじめに：MCPネイティブなGoogleマップデータへの道

Googleマップは、公開ウェブ上で最も豊富なビジネスデータセットの1つです — 名前、住所、評価、レビュー数、営業時間、写真リンク、カテゴリタグ、連絡先情報、そしてすべてのエントリに対する安定した場所IDがあります。ローカルSEOチーム、リード生成パイプライン、不動産分析、競合位置マッピングにとって、そのデータセットはワークフローの基盤です。

ページ自体は、実際のブラウザなしでは操作が難しいです。マップビューは独自のSDKをロードし、サイドパネルはフィードがスクロールするにつれてレイジーロードでページネーションを行い、個別の場所詳細パネルはユーザーのクリックを通じて開き、結果数はクエリあたり約120で上限に達します。純粋なHTTPスクレイピングはJSシェルを返し、データはレンダリングされたDOMの背後に存在します。

この記事では、Scrapeless MCP Serverを任意のMCP対応クライアント — Claude Desktop、Claude Code、Cursor、OpenAI Codex CLI、Gemini CLI、またはMCP TypeScript SDKに対して構築されたカスタムクライアント — と組み合わせて、Googleマップをエンドツーエンドでスクレイプする方法を説明します。サーバーは、エージェント対応のクラウドブラウザであるScrapeless Scraping Browserを一連のMCPツールとしてラップしているため、エージェントはプロトコルを介して直接browser_create / browser_goto / browser_scroll / browser_get_htmlを呼び出すことができます。クラウドブラウザはレンダリング、プロキシ、検出回避レイヤーを処理し、エージェントは発見 → 抽出パターンを処理します。

異なる統合表面を介した同じターゲットについては、LangChainエージェント投稿をご覧いただくか、bash CLIバージョンのより広範な検索エンジン投稿をご覧ください。

できること

• ローカルリード生成。 目標都市のすべての歯科医、配管工、コーヒーショップを名前、住所、電話、ウェブサイト、営業時間、評価、レビュー数で取得します。
• ローカルSEO競争分析。 カテゴリキーワードクエリにおける競合位置のランキングと、同じSERP上の周辺リストを追跡します。
• 不動産およびPOIデータセット構築。 カテゴリ化されたポイント・オブ・インタレストテーブルを構築します — 料理別のレストラン、地域別の小売チェーン、郵便番号別の公共サービス — リフレッシュはロールして行います。
• 評判の追跡。 マルチロケーションブランド全体での各場所の評価、レビュー数、レビュー速度のスナップショットを取得し、異常な場所を明らかにします。
• 市場調査。 目標エリアにおける中小企業の密度およびカテゴリミックスをマップし、市場の飽和度を推定します。
• 写真および価格インテリジェンス。 ビジュアル回帰のために場所パネルのスクリーンショットをキャプチャするか、各リスティングごとの価格レベルインジケーター（$、$$、$$$）を取得します。

スクラペスのないスクレイピングブラウザについて

スクラペスのないスクレイピングブラウザは、ウェブクローラーやAIエージェント専用に設計されたカスタマイズ可能なアンチディテクションクラウドブラウザです。特にGoogleマップにおいては、以下の機能があります：

• クラウド側のJavaScriptレンダリングにより、マップSDK、サイドフィード、スクロール駆動のレイジーロード、場所の詳細パネルがすべて抽出の前にポピュレートされます。
• 195か国以上の住宅プロキシを使用して、地理的に制約されたクエリがローカルユーザーが見えるリスティングを返すことができます — これは、Googleマップの結果が出口地域によって異なるため重要です。
• 各セッションでのアンチディテクションフィンガープリンティングにより、ページは長時間スクロールセッション中のオーガニックトラフィックと同じようにレンダリングされます。
• セッションの持続性：browser_createタスクIDを通じて。以降の同じエージェント内のbrowser_*ツールコールは、同じクラウドブラウザを再利用し、クッキー、スクロール位置、ナビゲーション履歴を一貫して保持します。
• 単一のMCPインターフェース — エージェントがマップを操作するために必要なすべての操作（browser_goto、browser_wait_for、browser_scroll、browser_click、browser_get_html、browser_get_text、browser_screenshot）がツールコールで行えます。

無料プランのAPIキーをScrapelessで取得してください。MCPツールインターフェースの詳細はgithub.com/scrapeless-ai/scrapeless-mcp-serverで文書化されています。

前提条件

• MCPをサポートする任意のクライアント：Claude Desktop（claude.com/download）、Claude Code、Cursor、OpenAI Codex CLI、Gemini CLI、またはデータモデルコンテキストプロトコルに基づいて構築されたカスタムクライアント — プロトコルが支えとなっています。
• Node.js 18以上（stdioトランスポートモード用）。
• ScrapelessアカウントとAPIキー — Scrapelessにサインアップしてください。
• クライアントのMCP設定ファイルを編集する基本的な知識。

インストール

Scrapeless MCPサーバーはscrapeless-mcp-servernpmパッケージとして公開されており、モデルコンテキストプロトコルをサポートする任意のクライアントから呼び出すことができます。以下の4ステップのセットアップは、最も一般的なクライアント（Claude Desktop、Claude Code、Cursor、OpenAI Codex CLI、Gemini CLI）用のインストールパスを示していますが、JSONスニペット自体はポータブルであり、お使いのチームがすでに使用しているクライアントにドロップすれば、そのまま同じツールコールが動作します。

1. Scrapeless APIキーを取得する

Scrapelessにサインアップし、ダッシュボードを開き、設定 → APIキー管理からキーを作成します。値をコピーします — これがステップ2のMCP設定に入ります。

無料プランのAPIキーを取得するには、Scrapelessにサインアップしてください。また、公式コミュニティにも参加できます：
Scrapeless公式Discordコミュニティ
Scrapeless公式Telegramコミュニティ

2. クライアントにMCPサーバーを追加する（stdioモード）

設定ファイルの場所はクライアントによって異なります：

Claude Desktop（claude.com/downloadからのデスクトップアプリ）：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Claude Code（ターミナルCLI）：

• すべてのプラットフォーム: ~/.claude.json
• または、手動でファイルを編集する代わりに、claude mcp addサブコマンドを使用します：
  bash Copy

  claude mcp add scrapeless --scope user --transport stdio \
    --env "SCRAPELESS_KEY=YOUR_SCRAPELESS_KEY" \
    -- npx -y scrapeless-mcp-server

Cursor：~/.cursor/mcp.jsonを編集します（または、Cursorの設定 → MCP UIを使用）。以下のスニペットと同じJSON形式です。

OpenAI Codex CLI：Codexは~/.codex/config.tomlからMCPサーバーを読み取り、codex mcpヘルパーも提供します。stdioインストールコマンドは以下の通りです：

codex mcp add scrapeless \
  --env "SCRAPELESS_KEY=YOUR_SCRAPELESS_KEY" \
  -- npx -y scrapeless-mcp-server

同等のTOMLは以下の通りです：

[mcp_servers.scrapeless]
command = "npx"
args = ["-y", "scrapeless-mcp-server"]

[mcp_servers.scrapeless.env]
SCRAPELESS_KEY = "YOUR_SCRAPELESS_KEY"

ファイルを編集した後、Codexを再起動し、codex mcp list --jsonでエントリを確認します。Codexはstdio MCPフレーミングに厳格です：サーバープロセスはstdoutにJSON-RPCメッセージのみを書き込む必要があります。CodexがMCPサーバーとのハンドシェイクに失敗しました、初期化レスポンス、または接続が閉じられましたと報告する場合、JSON-RPCレスポンスの前にサーバーがstdoutに起動ログ行を出力したか確認します。修正されたサーバーバージョンにアップグレードするか、サーバーの背後に小さなstdioフィルタを実行して、非JSON stdout行をstderrにリダイレクトします。
デフォルトのCodexパスとしてstdioモードを使用します。現在のCodex CLIビルドでは、ストリーミング可能なHTTPサーバー用にcodex mcp add --urlを公開していますが、ヘルパーの組み込み認証オプションはベアラートークンベースであり、ScrapelessのホストされたMCPエンドポイントはx-api-tokenヘッダーを期待しています。CodexのHTTPモードは、MCPサーバーのカスタムHTTPヘッダーをサポートしているCodexのバージョン/設定の場合のみ使用してください。

Gemini CLI: Geminiは、settings.json内のmcpServersを介してMCPサーバーをサポートし、さらにgemini mcpヘルパーがあります。Gemini CLI自体は現在、Node.js 20以降を必要とします。ユーザー全体のstdioインストールのためには、次のコマンドを実行します：

gemini mcp add -s user \
  -e SCRAPELESS_KEY=YOUR_SCRAPELESS_KEY \
  scrapeless npx -y scrapeless-mcp-server

または、~/.gemini/settings.jsonを直接編集します：

{
  "mcpServers": {
    "scrapeless": {
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": {
        "SCRAPELESS_KEY": "YOUR_SCRAPELESS_KEY"
      }
    }
  }
}

プロジェクトスコープの設定には.gemini/settings.jsonを使用します。設定が正しいかは、gemini mcp list（または、非対話型シェルでテーブルが表示されない場合はgemini --debug mcp list）で確認するか、Geminiを起動して/mcpを実行して接続状況と検出されたツールを確認してください。

VS Code + GitHub Copilot Chat: 同じmcpServersのスニペットをワークスペースまたはユーザーレベルのMCP設定に追加します。アクティブなパスについては、GitHub Copilot Chat MCPドキュメントを参照してください。

ScrapelessサーバーのエントリをmcpServersに追加します：

{
  "mcpServers": {
    "scrapeless": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "scrapeless-mcp-server"],
      "env": {
        "SCRAPELESS_KEY": "YOUR_SCRAPELESS_KEY"
      }
    }
  }
}

YOUR_SCRAPELESS_KEYを手順1で取得したキーに置き換えてください。新しいサーバーを取得するためにクライアントを再起動します。最初の実行時にnpx -y scrapeless-mcp-serverがパッケージをダウンロードして、stdio経由でサーバーを起動します — 別個のインストールコマンドは必要ありません。再起動後、クライアントのMCPパネルには、他の接続されたサーバーと並んでscrapelessが表示されるはずです。

3. もしくはHTTPストリーミングモードを使用（クラウドホストエージェント）

リモートで実行するエージェント — ホストされたCursorサーバー、CIランナー、コンテナ内で実行するカスタムMCPクライアント — は、npxをローカルで実行する代わりに、ScrapelessがホストするMCPエンドポイントを指す必要があります：

{
  "mcpServers": {
    "Scrapeless MCP Server": {
      "type": "streamable-http",
      "url": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "YOUR_SCRAPELESS_KEY"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

同じYOUR_SCRAPELESS_KEYは両方のモードで機能します。HTTPトランスポートは、stdioバイナリがエージェントと並行して実行できないときの正しいデフォルトです（CIサンドボックス、ホストされたエージェントランナー）。

Gemini CLIの場合、HTTPヘルパーとJSONの形状は次の通りです：

gemini mcp add -s user -t http \
  -H "x-api-token: YOUR_SCRAPELESS_KEY" \
  scrapeless https://api.scrapeless.com/mcp

{
  "mcpServers": {
    "scrapeless": {
      "httpUrl": "https://api.scrapeless.com/mcp",
      "headers": {
        "x-api-token": "YOUR_SCRAPELESS_KEY"
      }
    }
  }
}

4. MCPサーバーが接続されているか確認する

最初の実際のマップスクレイプの前に、次のプロンプトを使ってインストールをスモークテストします：

"Scrapeless MCPサーバーを使用してhttps://example.comを開き、ページタイトルを教えてください。"

エージェントはbrowser_createを呼び出してセッションを作成し、次にbrowser_gotoでナビゲートし、次にbrowser_get_text（またはbrowser_get_html）を実行して**"Example Domain"**と返答します。それが返ってくる場合、MCPサーバーが読み込まれており、APIキーが設定されていて、クラウドブラウザにアクセスできることを意味します。

失敗した場合：

実際にこれを使用する方法：エージェントにプロンプトを送信する

インストール後、Googleマップをスクレイプするためには、エージェントと会話する必要があります — ツール呼び出しを手動でコーディングするのではありません。MCPサーバーはクラウドブラウザを発見可能なツールリストとして公開し、エージェントはツールの説明を読み、それに基づいて正しい順序で構成します。

貼り付け可能なプロンプト

ツール呼び出し（エージェントがMCPを通じて送信するもの）:

{
  "name": "browser_create",
  "arguments": {}
}

ツールはNew browser session created with ID: vybp-a64d-2dqf-9vsq86のようなペイロードを返します。同じエージェント内のその後のbrowser_*呼び出しは自動的にアクティブなセッションを再利用します; 返されたIDをsessionIdとして渡すことはサポートされていますが、必須ではありません。

プロキシ地域はScrapelessアカウント設定によって設定されます—MCP browser_createツールは、呼び出しごとのproxyCountry引数を公開していません。クエリごとの地域の制御が必要なワークフロー（米国の地図結果対スペイン対日本）には、代わりにscrapeless-scraping-browser CLIを直接使用し、--proxy-countryを指定するか、異なる地域用に設定された複数のScrapeless APIキーを実行してください。

呼び出しが一時的な接続エラーを返した場合は、エージェントに一度再試行するように依頼してください。プロキシプールは、割り当て時に利用可能な住宅用IPを返さないことがあるため、新しいbrowser_createは次の試行で成功します。

ステップ2 — マップ検索URLに移動する(browser_goto)

Google Mapsは検索のためのディープリンクURLパターンを公開しています: https://www.google.com/maps/search/<query>。クエリをURLエンコードし、その検索用にサイドフィードが populatedで読み込まれます。

{
  "name": "browser_goto",
  "arguments": {
    "url": "https://www.google.com/maps/search/coffee+shops+in+Pike+Place+Seattle"
  }
}

このURL形式は、エージェントを検索ボックスを使わずに populatedなSERPに直接導きます。これによりフローが短くなり、エージェントが誤って操作をクリックする可能性を減らします。

同意画面の処理。 クラウドブラウザーがヨーロッパの住宅用プロキシを介してルーティングされると、Googleはマップを表示する前にconsent.google.comで同意画面を表示します。エージェントはbrowser_gotoの後にbrowser_get_textを呼び出し、レスポンスに「consent」または「Accept all」/ローカライズされた同等物（Accetta tutto、Akzeptieren、Accepter）が含まれているかどうかを確認すべきです。はいの場合は、Acceptボタンに対してbrowser_clickを実行します—アクセス可能なラベルは地域を超えて機能します:

{
  "name": "browser_click",
  "arguments": {
    "selector": "button[aria-label*='Accept' i], form[action*='consent'] button:last-of-type"
  }
}

クリックの後に、再度browser_gotoを実行してマップページ自体に到達します。米国のプロキシ地域を介して実行されるワークフローは、通常この壁にぶつかりません。

ステップ3 — フィードのレンダリングを待つ(browser_wait_for)

マップのSPAは波のように描画されます: 最初にマップキャンバス、その後サイドフィードシェル、最後にプレイスカードがレンダリングされます。抽出する前にプレイスカードのランドマークで待機してください。さもなければ、結果の地域は空になります。

{
  "name": "browser_wait_for",
  "arguments": {
    "selector": "a.hfpxzc"
  }
}

a.hfpxzcは、サイドフィード内のオーガニックカードごとの標準的なプレイスリンクアンカーで、プレイス名はaria-labelにあり、標準的な/maps/place/<slug>/data=!1s<placeId>のURLはhrefにあります。これは、カードがレンダリングされたことを示す最も信頼性のあるシグナルです。なぜなら、記事のランドマークは水分補給中にリンクアンカーの後ろに遅れることがあるからです。

待機がタイムアウトした場合、そのページはインタースティシャルに到達した（稀）か、クエリに対してフィードが本当に空であることを示しています。エージェントにbrowser_get_textを呼び出して、可視ページのテキストをダンプし、どのケースであるかを確認させてください。

ステップ4 — フィードをスクロールしてさらに結果を遅延ロードする(browser_scroll, browser_press_key)

サイドフィードは最初に約10〜20枚のカードをレンダリングします。その後のバッチは、フィードスクロールに応じて遅延ロードされ、クエリごとの上限である約120のプレイスに達します。

MCPサーバーは2つのスクロールプリミティブを公開しています:

• browser_scroll — ページをスクロールし、パラメーターは不要です（アクティブなドキュメントに作用します）。
• browser_scroll_to — 絶対的なピクセル座標にスクロールします。必要な引数: {x, y}の数値。

{
  "name": "browser_scroll",
  "arguments": {}
}

Google Mapsでは、サイドフィードはそれ自体のスクロール可能なコンテナであり、ページそのものではないため、通常のbrowser_scrollは遅延ロードを進めない場合があります。信頼できるパターンは、まず任意のレンダリングされたカードに対してbrowser_clickでフィードに焦点を合わせ、その後browser_press_keyでキーボードスクロールを実行することです:

{
  "name": "browser_click",
  "arguments": { "selector": "a.hfpxzc:first-of-type" }
}

{
  "name": "browser_press_key",
  "arguments": { "key": "End" }
}

典型的なフローは、最初のカードをクリックし、その後にbrowser_press_keyで「End」や「PageDown」を3〜5回押し、その合間に1500msのbrowser_waitを設けて遅延ロードが完了するのを待ってから次のキー押下を行います。
深いスクレイプの場合、エージェントは各スクロール後にカードの数を監視する必要があります：2回連続してbrowser_get_html呼び出しが同じ数を返す場合、フィードはクエリごとの上限に達したことを意味し、これ以上のスクロールでは結果が追加されません。

ステップ5 — プレースカードの抽出（browser_get_html）

フィードが希望の数のカードをレンダリングしたら、完全なHTMLを引き出し、エージェントに解析させます。

{
  "name": "browser_get_html",
  "arguments": {}
}

browser_get_htmlは、レンダリングされた全DOMを単一のテキストペイロードとして返します — 地域ごとのセレクター引数はありません；エージェントは、レスポンスが届いた後にメモリ内でHTMLをスライスします。各オーガニックカードは1つの<a class="hfpxzc">アンカーとして現れます；それらを解析してプレースごとのフィールドを取得します：

placeIdは、複数のセッションやタイルにわたって同じクエリを実行する際の負荷のかかる重複除外キーです。

ステップ6 — オプション：詳細パネルを掘り下げる（browser_click + browser_get_html）

各場所について、エージェントはカードをクリックして詳細パネルを開き、より豊富なフィールドを抽出できます — 完全な住所、電話番号、ウェブサイト、営業時間、最新のレビュー。

{
  "name": "browser_click",
  "arguments": {
    "selector": "a.hfpxzc[href*=\"<placeId>\"]"
  }
}

クリックの後、詳細パネルランドマークがレンダリングされるのを待ちます：

{
  "name": "browser_wait_for",
  "arguments": {
    "selector": "h1.DUwDvf"
  }
}

h1.DUwDvfは詳細パネル内の場所名の見出しです — パネルが完全に描画されたという最もクリーンなサインです。それから、パネルに対してbrowser_get_htmlを呼び出し、解析します：

掘り下げはプレースごとのリクエストコストを増加させます；実際にワークフローがパネル専用フィールドを必要とする場合のみ実行します。

ステップ7 — スクリーンショットの取得（browser_screenshot）

スクリーンショットは視覚的な回帰、苦情証拠収集、またはエンドツーエンドの検証に役立ちます。エージェントはフローの任意のポイントでbrowser_screenshotを呼び出し、画像を受け取ります。

{
  "name": "browser_screenshot",
  "arguments": {
    "fullPage": true
  }
}

Google マップのフルページスクリーンショットには、サイドフィードとマップキャンバスの両方が含まれます。フィードのみのスクリーンショットを取得するには、フィードをトップにスクロールし、代わりにビューポートサイズのスクリーンショットを取得します。

ステップ8 — セッションを閉じる（browser_close）

エージェントが完了したら、browser_closeを呼び出してクラウドブラウザを解放します。このツールはbrowser_createによって返されたsessionIdを必要とします：

{
  "name": "browser_close",
  "arguments": {
    "sessionId": "vybp-a64d-2dqf-9vsq86"
  }
}

セッションを迅速に解放することで、アカウントの同時セッション数をクリーンに保ち、すべてのスクレイプの終わりにおける正しいデフォルトとなります。

クエリ上限を超えるスケーリング

Google マップは単一の検索を約120件の場所に制限しています。それを超えるクエリ — 「マンハッタンのすべてのレストラン」、「カリフォルニアのすべての歯科医」 — に対する戦略は、地理的なグリッドを使用します：

1. 検索エリアを小さなバウンディングボックスにタイル分けします。 近隣、郵便番号、または2km × 2kmの正方形は通常120件未満の結果を返すため、各タイルを完全に使い果たします。
2. 各タイルごとに1つのクエリを実行します。 マップのURL内に@lat,lng,zoomセグメントを埋め込むか（例：https://www.google.com/maps/search/coffee/@47.6097,-122.3331,15z）、クエリ文字列を変更します（「パイクプレイスのコーヒーショップ」→「べルタウンのコーヒーショップ」→「キャピトルヒルのコーヒーショップ」）。
3. placeIdによるタイル間の重複排除。 1つの場所はオーバーラップしたタイルに表示される可能性があります。mapUrlから解析されたplaceId（!1s0x<hex>:0x<hex>）は安定した結合キーです。

同じパターンがMCPプリミティブから構成されています — 1つのbrowser_create + 1つのbrowser_goto + スクロール + タイルごとに抽出し、エージェントは会話メモリ内でタイル間の重複排除セットを維持します。

結果として得られるもの

MCPツールは生のテキスト（HTML、ページテキスト、スクリーンショット）を返します。JSONの形状はエージェントが組み立てるものです。上記のdiscover → extractテンプレートを使用した単一検索およびスクロールパスの場合、スキーマは以下のようになります。

// スキーマは、場所カードの抽出を促されたときにエージェントが出力する内容を反映しています。
// フィールド値は示例サンプルです。
{
  "query": "パイクプレイスシアトルのコーヒーショップ",
  "queryUrl": "https://www.google.com/maps/search/パイクプレイスシアトルのコーヒーショップ",
  "resultsReturned": 15,
  "results": [
    {
      "name": "ストーリービルコーヒー パイクプレイス",
      "rating": 4.8,
      "reviewCount": 3174,
      "address": "94 Pike St #34, Seattle, WA 98101",
      "category": "コーヒーショップ",
      "priceLevel": "$$",
      "mapUrl": "https://www.google.com/maps/place/ストーリービルコーヒー+パイクプレイス/data=!4m7!3m6!1s0x54906ab2f0c61d05:0x771b2a7dce963d58!8m2!3d47.60895!4d-122.3404309",
      "placeId": "0x54906ab2f0c61d05:0x771b2a7dce963d58",
      "isSponsored": false,
      "phone": null,
      "website": null,
      "hours": null
    }
  ]
}

この出力についてのいくつかの正直な観察で、スケールで実行する前に知っておくべきことがあります。

• ハイドレーションタイミング。 マップSPAは波のようにレンダリングされます — マップキャンバス、その後フィードシェル、そしてカード。a.hfpxzcに対してbrowser_wait_forが抽出を制御します。エージェントの最初のbrowser_get_htmlがシェルのみを返す場合は、もう少し待って再抽出するように指示してください。
• セレクタの安定性。 [role="article"]、[role="feed"]、評価ウィジェットのaria-label文字列、及び正規のmapUrlに対するa.hfpxzc[href]が最も長く生き残るアンカーです。クラス名（例：h1.DUwDvf、.jftiEf）は今日のところは機能しますが、デプロイ間でローテーションします; これらを最善努力と見なし、将来のスクレイプで空の結果が返ってきた場合は再度discoverパスを実行してください。
• スポンサー付き配置。 スポンサー付きカードはオーガニック結果と交互に配置され、[aria-label="Sponsored"]を持っています。エージェントはそれらをドロップするのではなく、isSponsoredを設定すべきですので、下流の消費者が明示的にフィルタリングできます。
• 詳細パネルフィールドは条件付き。 電話番号、ウェブサイト、営業時間は、すべての場所に存在しないbutton[data-item-id="…"]行から取得されます。それらは必須ではなくnullableとして扱ってください。
• ロケールと言語。 場所カードのUIテキスト（"hours"、"reviews"、"website"ボタンラベル）はプロキシ国の言語にローカライズされます。米国発のクエリの場合、ラベルは英語ですが、スペイン語、フランス語、日本語の場合、パーサーの正規表現はローカライズされた文字列に一致する必要があり、フィールドはnullが返されます。
• クエリあたりの上限。 サイドフィードにはクエリあたり約120件の結果があります。大きな地理では、上記の地理グリッドタイルパターンを使用し、placeIdで重複排除してください。

よくある質問

Q1: Googleマップ用にプロキシは必要ですか？地域を選べますか？
すべてのクラウドブラウザセッションは、Scrapelessの住宅プロキシを自動的に経由します — 呼び出しが機能するために別途のプロキシ設定は必要ありません。ただし、プロキシ地域はアカウントレベルで設定されており、MCPのbrowser_createツールの呼び出しごとの引数としては公開されていません。クエリあたりの地域制御が必要なワークフロー（米国マップの結果とスペイン、そして日本）では、scrapeless-scraping-browser CLIを使用してクラウドブラウザを駆動する必要があります（--proxy-countryを公開します）か、異なるデフォルト地域用に構成された複数のScrapeless APIキーを維持してください。

Q2: stdioとHTTPストリーミングモードの違いは何ですか？
Stdioモードはnpx scrapeless-mcp-serverをMCPクライアント（Claude Desktop、Cursor など）の子プロセスとして実行し、デスクトップエージェントに対する適切なデフォルトです。HTTPストリーミングモードはクライアントをhttps://api.scrapeless.com/mcpに向けており、npxにシェルを出せないクラウドホスト型エージェントに対する適切なデフォルトです。両方のモードとも同じScrapeless APIキーを使用します。

Q3: クエリの120件上限を超えるにはどうすればよいですか？
検索エリアを小さな地理（近隣、郵便番号、緯度/経度の境界ボックス）にタイル分けし、タイルごとに1つのクエリを実行します。重複排除のためにオーバーラップしたタイル間で導出されたplaceId（mapUrlの!1s0x<hex>:0x<hex>セグメントから）を使用してください。地理グリッドパターンは、クエリあたりの上限を超えるスケーリングセクションに文書化されています。

Q4: 場所からレビューを抽出できますか？
はい。フィードがレンダリングされた後、カードをクリックして詳細パネルを開き、h1.DUwDvfを待ち、次に.jftiEf領域からレビューカードを抽出します — タイトル、著者、評価、本文、日付。掘り下げは場所ごとに行われ、リクエストコストが増加します; ワークフローがレビューペイロードを必要とする場合のみ実行してください。

Q5: GoogleマップがDOMを変更したらどうなりますか？
再度ディスカバーパスを実行する：エージェントに関連地域で browser_get_html を呼び出すよう依頼し、現在の安定したアンカーを再特定します。 [role="article"]、[role="feed"]、aria-label ストリング、および a.hfpxzc[href] が最も長生きします。クラス名はローテーションします。スキルのディスカバ → 抽出パターンは、コードの変更なしにこれを処理します。

Q6: なぜ私のセッションは時々 Access Denied または CAPTCHA ページを返すのですか？
新しいプロキシの割り当ては、時折フラグ付きの IP アドレスに割り当てられます。エージェントに browser_close を呼び出し、その後再度 browser_create を呼び出して新しいセッションを作成するよう依頼してください。その後の割り当ては成功します。

Q9: 複数のエージェントが1つの MCP サーバーを共有できますか？
各 MCP 対応クライアントは、専用のサーバーインスタンス（stdio モード）や共有されている HTTP エンドポイント（ストリーミングモード）に接続します。セッションは browser_create から返される taskId によって隔離されるため、同じ MCP サーバーを呼び出す複数のエージェントはクッキーやスクロール状態を共有しません。高ファンアウトのスクレイプには、単一の長寿命セッションを再利用するのではなく、クエリごとに1つのセッションを作成してください。

Q10: これはどの MCP クライアントで動作しますか？
MCP をサポートする任意のクライアント。 プロトコルが契約です — サーバーのツールリストと呼び出し形状は、すべてのクライアント間で同一です。ステップ 2 では、Claude Desktop、Claude Code、Cursor、OpenAI Codex CLI、Gemini CLI、VS Code + GitHub Copilot Chat のセットアップパスが含まれており、同じ mcpServers JSON スニペットは、MCP TypeScript SDK に基づいて構築されたカスタム Python または Node クライアントにドロップできます。また、ストリーミング可能な HTTP エンドポイント https://api.scrapeless.com/mcp は、任意の HTTP クライアントで動作します。

Q11: MCP サーバーには専用の Google Maps ツールがありますか？
いいえ — サーバーは一般的なブラウザのプリミティブ（browser_create、browser_goto、browser_wait_for、browser_get_html、browser_get_text、browser_click、browser_type、browser_press_key、browser_scroll、browser_scroll_to、browser_screenshot、browser_snapshot、browser_close）とページレベルのヘルパー（scrape_html、scrape_markdown、scrape_screenshot）および Google データツール（google_search、google_trends）を提供します。エージェントはブラウザのプリミティブからマップのスクレイプを構成します。同じプリミティブが Amazon、Home Depot、Etsy、その他の JavaScript が重いサイトを駆動します。

Q12: なぜ Maps が検索結果ではなく同意ページを読み込むのですか？
クラウドブラウザのセッションがヨーロッパの住宅プロキシを通じてルーティングされる場合、Google はマップを表示する前に consent.google.com の中間ページでナビゲーションを中断します。エージェントは browser_goto の後に browser_get_text を呼び出し、応答に「同意」や Accept ボタンのラベル（Accept all / Accetta tutto / Akzeptieren / Accepter）が含まれている場合、ナビゲーションを再試行する前にボタンに対して browser_click を実行すべきです。ステップ 2 では完全なスニペットがカバーされています。

Q13: なぜ私のセッションは時折 os error 10054 や 503 のような一時接続エラーを返すのですか？
Scrapeless 住宅プロキシプールは、時折 browser_create で短命な割り当てエラーを返します。単一のリトライが通常成功します — プロダクションコードでは browser_create を2–3回の試行のリトライループでラップするか、単にエージェントに一度リトライするよう依頼してください。

Q14: どれくらいの MCP スクレイピングジョブを同時に実行できますか？
信頼性のために、1つの MCP クライアントに対して1つの進行中のセッションを保持し、単一のエージェントターン内で呼び出しを連鎖させてください。ファンアウトを高めるには、複数の MCP クライアント（またはストリーミング可能な HTTP エンドポイントに接続するワーカープロセス）を実行し、ホストごとの同時実行を ≤ 3 セッションに制限してください。純粋なスループットバッチジョブ（10K+ クエリ/時）には、scrapeless-scraping-browser CLI を直接平行ワーカープールで駆動してください。MCP パスはエージェント主導の発見とタイルベースの地理的カバレッジに最適です。

Q15: MCP クライアントなしでこれを実行できますか？
はい。2つのパス：(1) 任意の HTTP クライアントから https://api.scrapeless.com/mcp のストリーミング可能な HTTP エンドポイントを x-api-token ヘッダーで直接呼び出す；(2) scrapeless-scraping-browser CLI を通じてクラウドブラウザを bash 経由で駆動します。MCP ドリブンのワークフローは、エージェントが促すスクレイピングの推奨パスです；CLI はスクリプト化されたバッチパイプラインのための適切なパスです。

Q16: なぜ検索ボックスを操作するのではなく、標準の /maps/search/<query> URL を使用するのですか？
ディープリンク検索 URL は、エージェントを検索入力をクリックせずにポピュレートされた SERP に直接送ります。ツールコールが少なく、エージェントが間違ったコントロールをクリックする可能性が低く、エンドツーエンドの実行が速くなります。場所 URL に対しても同じアプローチを使用します：placeId が既に知られている場合、/maps/place/<slug>/data=!1s<placeId> に直接ナビゲートせず、検索してからクリックします。