Hubertino: Google Maps leads

Hubertino MCP サーバー：Claude、Cursor、その他の AI エージェント向け Google Maps リード

@hubertino/mcp-server は、あらゆる Model Context Protocol クライアント（Claude Desktop、Claude Code、Cursor、VS Code など）を、Google Maps のリード情報をスクレイピングする Hubertino に接続します。「オースティンのメールアドレスがある歯科医」とアシスタントに頼むだけです。スクレイピングを開始して完了まで待ち、リードをテーブル、または CSV／XLSX ファイルで受け取れます。

Hubertino の認証済みパブリック REST API（ドキュメント）をラップしており、ご自身の API キーとクレジットを使用します。

利用できる機能

各リードは、Google Maps 上の 1 件のビジネスに対応します。値があるフィールドのみが返されます。

• 連絡先： 名前、カテゴリ、電話番号、ウェブサイト、およびビジネスの公式ウェブサイトで見つかったメールアドレス（enrichWebsite）。
• ソーシャルプロフィール： Facebook、Instagram、LinkedIn、X、YouTube（enrichLinks）。
• 所在地： 住所、市区町村、州、郵便番号、国コード、Google Maps リンク／プレイス ID。
• 評判： 評価、レビュー数、ビジネスのステータス。
• 追加フィールド（コンテキストを節約するため、コンパクトな結果からは除外）： 座標、営業時間、価格帯、サービスオプション、注文／予約／メニューのリンク。get_results の detail: "full" で取得するか、download_export ファイルで確認できます。

ツール

ツール	機能	API 呼び出し
start_scrape	categories × locations のスクレイピングを開始します。クレジットを使用します。	POST /api/v1/scrapes
get_scrape	ステータス、進捗状況、予約・消費したクレジット数、メールアドレスや電話番号などを含む行数を返します。	GET /api/v1/scrapes/{id}
wait_for_scrape	スクレイピングが完了するか、タイムアウト（デフォルトは 50 秒）になるまでポーリングします。進捗状況の通知を送信します。	GET /api/v1/scrapes/{id}
list_scrapes	最近のスクレイピングを一覧表示します。ステータスで絞り込むこともできます。	GET /api/v1/scrapes
get_results	リードの行をページ分割されたコンパクトな JSON で返します。オプション：withEmailOnly、fields、detail。	GET /api/v1/scrapes/{id}/results
download_export	完了したスクレイピング結果を .xlsx または .csv 形式でコンピューターに保存します。	GET /api/v1/scrapes/{id}/export

また、ビジネスの種類と地域を指定してワークフロー全体を実行する build_lead_list プロンプトもあります。

start_scrape は API と同じ入力値と制限を使用します。

入力	型	備考
categories	string[]	必須。検索対象を指定します。例：["dentist"]。1～1,000 件、各項目は 1～120 文字です。
locations	string[]	必須。都市、地域、または郵便番号を指定します。国も含めてください。例："Austin, TX, United States"。1～10,000 件です。
maxResults	integer	必須。検索ごと（カテゴリ × 地域の組み合わせごと）の最大場所数。1～500 件です。
country	string	任意。Google のエディションコード（us、gb、de、lt など、32 種類）。省略した場合は地域から推定されます。
enrichWebsite	boolean	デフォルトは true。メールアドレスを見つけるために、各ビジネスのウェブサイトにアクセスします。追加のクレジットは不要です。
enrichLinks	boolean	デフォルトは true。ソーシャルプロフィールと注文／予約リンクを収集します。追加のクレジットは不要です。

1 回のスクレイピングで実行できる検索は最大 2,000 件です（categories.length × locations.length）。

要件

• Node.js 20 以降（npx が MCP クライアントの使用する PATH に含まれている必要があります）。
• Hubertino アカウントと API キー。新規アカウントには 100 クレジットが無料で付与され、API は無料プランを含むすべてのプランで利用できます。
  1. hubertino.com で登録します。
  2. Settings（/dashboard/settings）を開き、API キーを作成します。キーは hub_live_ で始まり、一度しか表示されないため、すぐにコピーしてください。

インストール

どのクライアントでも必要な手順は同じです。環境変数に HUBERTINO_API_KEY を設定して、npx -y @hubertino/mcp-server を実行します。hub_live_your_key_here をご自身のキーに置き換えてください。

Claude Desktop

Settings → Developer → Edit Config を開きます。claude_desktop_config.json が開きます。このファイルは、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json に、Windows では %APPDATA%\Claude\claude_desktop_config.json にあります。次の内容を追加します。

{
  "mcpServers": {
    "hubertino": {
      "command": "npx",
      "args": ["-y", "@hubertino/mcp-server"],
      "env": {
        "HUBERTINO_API_KEY": "hub_live_your_key_here"
      }
    }
  }
}

Claude Desktop を再起動します。Hubertino のツールがツールメニューに表示されます。

ワンクリックでインストールできるバンドル（hubertino-mcp.mcpb）は、npm run bundle でビルドして Claude Desktop で開けます。フォームにキーを入力するため、JSON を編集する必要はありません。

Claude Code

claude mcp add hubertino -e HUBERTINO_API_KEY=hub_live_your_key_here -- npx -y @hubertino/mcp-server

すべてのプロジェクトで使えるようにするには、--scope user を追加します。claude mcp list を実行して、接続されていることを確認します。

Cursor

サーバーを ~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1 つのプロジェクト）に追加します。

{
  "mcpServers": {
    "hubertino": {
      "command": "npx",
      "args": ["-y", "@hubertino/mcp-server"],
      "env": {
        "HUBERTINO_API_KEY": "hub_live_your_key_here"
      }
    }
  }
}

VS Code（GitHub Copilot エージェントモード）

.vscode/mcp.json に次の内容を追加します。VS Code がキーの入力を求め、安全に保存します。

{
  "inputs": [
    { "type": "promptString", "id": "hubertino-key", "description": "Hubertino API key (hub_live_...)", "password": true }
  ],
  "servers": {
    "hubertino": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@hubertino/mcp-server"],
      "env": { "HUBERTINO_API_KEY": "${input:hubertino-key}" }
    }
  }
}

その他のクライアント／ソースから実行する場合

stdio サーバーを起動できる MCP クライアントであれば、どれでも動作します。チェックアウトしたソースから実行するには、次のようにします。

git clone https://github.com/hubertino-app/hubertino-mcp.git
cd hubertino-mcp && npm install && npm run build
# then point your client at:  node /absolute/path/to/hubertino-mcp/dist/index.js

設定

変数	必須	デフォルト	用途
HUBERTINO_API_KEY	はい	なし	お使いの hub_live_... キーです。キーが設定されていなくてもサーバーは起動し、各ツールが設定方法を説明します。
HUBERTINO_API_URL	いいえ	https://hubertino.com	API のベース URL です。https://hubertino.com/api/v1 も使用できます。localhost を除き、https:// のみ受け付けます。
HUBERTINO_DOWNLOAD_DIR	いいえ	~/Downloads、利用できない場合は一時ディレクトリ	download_export がファイルを保存する場所です。

プロンプトの例

• 「テキサス州オースティンの歯科医を、メールアドレス付きで探してください。検索ごとに 100 件で十分です。」
• 「英国のリーズとヨークで配管工と電気技師のリストを作成し、CSV として保存してください。」
• 「次の郵便番号で屋根工事業者をスクレイピングしてください：78701、78702、78703。メールアドレスとウェブサイトがある業者だけを表示してください。」
• 「直近のスクレイピングの状況を教えてください。」
• 「カフェのスクレイピング結果の 2 ページ目を表示してください。名前、電話番号、Instagram のみでお願いします。」
• 「完了したスクレイピングのうち、結果が最も多かったものはどれですか？Excel 形式でダウンロードしてください。」

一般的な実行例は次のとおりです。

start_scrape     {"categories":["dentist"],"locations":["Austin, TX, United States"],"maxResults":100}
  -> {"id":"6f1c…","status":"queued","credits":"Reserved 100 credits … the rest is refunded automatically.", …}
wait_for_scrape  {"scrapeId":"6f1c…"}
  -> {"status":"done","resultCount":…,"creditsCharged":…,"coverage":{"total":…,"email":…}, …}
get_results      {"scrapeId":"6f1c…","withEmailOnly":true,"limit":50}
  -> {"total":…,"returned":…,"hasMore":true,"nextOffset":50,"rows":[{"name":"…","phone":"…","email":"…"}, …]}
download_export  {"scrapeId":"6f1c…","format":"csv"}
  -> {"path":"/Users/you/Downloads/hubertino-6f1c….csv","bytes":…}

クレジット、制限、エラー

• 1 クレジット = 1 件のビジネス情報を納品。 スクレイピングを開始すると、Hubertino は categories × locations × maxResults クレジットを、お客様の残高を上限として確保します。完了時には、実際に納品された行の分だけ課金され、残りは返金されます。残高が最悪のケースに必要な額を下回っていても、スクレイピングは実行されますが、残高を使い切ると停止します。料金をご覧ください。
• 速度： スクレイピングには数分かかります。実行中でも行を読み取れます（partial: true）。各行の _status は found → extracted → enriched の順に変わります。
• レート制限： アカウントごとに、5 分間に開始できる新しいスクレイピングは 12 件です。ステータス、結果、エクスポートの呼び出しにはレート制限はありません。
• ページサイズ： get_results は 1 回の呼び出しで最大 1,000 行（デフォルトは 50 行）を読み取ります。モデルのコンテキストウィンドウを保護するため、1 回のツール応答に収まらないページ（約 50,000 文字）は途中で切り詰められ、trimmed: true が設定されます。nextOffset からページングを続けるか、fields で列を減らすか、download_export を使ってすべてのデータを取得してください。
• 長時間のスクレイピング： get_scrape と wait_for_scrape は、カテゴリやロケーションを最大 25 件まで返し、それより長いリストには categoriesTotal / locationsTotal を追加します。API の応答が遅い場合でも、wait_for_scrape が timeoutSeconds を約 8 秒以上超えて実行されることはありません。
• エクスポート： ステータスが done になった後にのみ利用できます。

エラーは次の手順とともにツールエラーとして返されるため、アシスタントは復旧するか、必要な対応を案内できます。

HTTP	意味	ツールが示す内容
400	入力が無効です	無効なフィールドを示す API のメッセージ
401	キーがない、または無効です	HUBERTINO_API_KEY を確認してください。Settings で作成またはローテーションできます
402	クレジットが不足しています	課金はされていません。/dashboard/billing でチャージしてください
403	拒否されました（例：メールアドレスが未確認）	API のメッセージ
404	不明なスクレイピング ID です	list_scrapes で ID を確認してください
409	まだ完了していません	wait_for_scrape で待ってから再試行してください
410	結果が保存されていません	新しいスクレイピングを開始してください
429	レート制限中です	次のスクレイピングを開始する前に数分待ってください
5xx	一時的に利用できません	1 分後に再試行してください
timeout / network	Hubertino から応答がありません	しばらくしてから再試行してください

スクレイピングの開始時にタイムアウト、ネットワークエラー、または 5xx が発生した場合でも、スクレイピングが作成されている可能性があります。その場合、start_scrape は再度開始する前に list_scrapes を確認するよう案内します。これにより、同じスクレイピングが 2 回実行され、課金されるのを防げます。

セキュリティとプライバシー

• API キーは MCP クライアントの設定内に保持され、HTTPS 経由で Hubertino API に Bearer ヘッダーとしてのみ送信されます。サーバーがキーをログに記録したり、応答で返したりすることはありません。キーをチャットに貼り付けないでください。
• サーバーは、上記に記載された認証済みの /api/v1 エンドポイントのみを呼び出します。それ以外のネットワーク呼び出しは行わず、スクレイピング自体も行いません。
• download_export は、選択したフォルダーに hubertino-<scrape id prefix>.csv / .xlsx ファイルのみを書き込み、既存のファイルを上書きすることはありません。
• リードデータは合法的に使用してください。適用されるプライバシーおよび迷惑メール防止のルール（たとえば GDPR、PECR、CAN-SPAM）を遵守してください。

開発

npm install
npm run build        # compile to dist/
npm test             # type-check and run the node:test suites (mocked fetch; no network)
npm run smoke        # spawn dist/index.js over stdio and list tools (set HUBERTINO_API_KEY for a live read-only call)
npm run bundle       # build hubertino-mcp.mcpb (Claude Desktop / Smithery bundle)

# optional: compare mirrored limits with a local checkout of the Hubertino app
HUBERTINO_APP_DIR=/path/to/hubertino/app npm test

公開手順については PUBLISHING.md をご覧ください。

リンク

• API ドキュメント：https://hubertino.com/docs
• 料金：https://hubertino.com/pricing
• Google Maps スクレイパー：https://hubertino.com/google-maps-scraper
• アフィリエイトプログラム（継続報酬 25%）：https://hubertino.com/partners

ライセンス

MIT © Hubertino MB