mapsdata

mapsdata

mapsdataは、Google MapsのデータをJSONで返す、ホスト型のHasData Google Maps MCP サーバーへの小規模なローカルブリッジです。キーワードで場所を検索し、必要に応じてGPS座標の周辺に絞り込み、評価、営業時間、電話番号、ウェブサイトを含む場所の基本情報を取得できます。その後、placeIdを使って場所の詳細、レビュー、写真ギャラリー、最新の投稿や特典を取得できます。6つ目のツールでは、1人のローカルガイド投稿者が書いたレビューをすべて一覧表示し、レビュアーのプロフィールや信頼性を確認できます。

このブリッジは、場所のデータを独自に保持しません。稼働中のエンドポイントから取得した内容そのままの上流サーバーのツール一覧をローカルで提供し、各ツールの呼び出しを上流に転送して、結果を変更せずに返します。ツール群が読み取り専用で扱うのは、Google Mapsで公開されている場所とレビュアーのデータのみです。投稿、メッセージ送信、予約のツールはありません。

ツール

• hasdata_google_maps_search_performMapSearch — Google Maps検索を実行します。必須：q。任意：domain、gl、hl、start（オフセットによるページ指定）、ll（GPS座標を@lat,lng,zoomz形式で指定。startを指定する場合は必須）。placeId、名前、住所、座標、評価、レビュー数、価格帯、カテゴリ、電話番号、ウェブサイト、営業時間、サムネイルを含む場所の基本情報を返します。
• hasdata_google_maps_place_getPlaceDetails — 1つの場所の詳細を取得します。必須：placeId。任意：domain、hl、fetchWebResults（場所のパネルに表示されるウェブ検索結果も返します）。名前、住所、座標、電話番号、ウェブサイト、カテゴリ、営業時間、評価、レビュー数、価格帯、写真、属性、plus codeを返します。
• hasdata_google_maps_reviews_getMapReviews — dataIdまたはplaceIdを指定して、1つの場所のレビューをページ単位で取得します。任意：hl、sortBy（mostRelevant、newestFirst、ratingHigh、ratingLow）、topicIdによる絞り込み、nextPageToken。投稿者、評価、テキスト、日付、いいね数、オーナーからの返信、写真、ローカルガイドのフラグを返します。
• hasdata_google_maps_photos_getMapPhotos — dataIdまたはplaceIdを指定して、1つの場所の写真ギャラリーを取得します。nextPageTokenでページ指定でき、categoryIdで絞り込めます。各写真の画像URLとサムネイルを返します。
• hasdata_google_maps_posts_getMapPosts — dataIdまたはplaceIdを指定して、1つの場所の最新のGoogle Maps投稿（特典、イベント、お知らせ）を取得します。hlで対象言語を指定できます。投稿ごとにタイトル、説明、画像、投稿日、リンク、ビジネス名を返します。
• hasdata_google_maps_contributor_reviews_getMapReviews — 1人のローカルガイドが投稿したレビューをすべて取得します。 必須：contributorId。任意：hl、gl、 num（1ページあたり10～200件）、nextPageToken。 レビューごとに評価、テキスト、日付、場所の名前と住所、 写真、オーナーからの返信を返します。

設定

• HASDATA_GOOGLE_MAPS_MCP_URL（任意）— 上流エンドポイントを上書きします。デフォルトは https://mcp.hasdata.com/mcp?apis=google_mapsです（クエリ文字列も固定されたURLの一部です）。この上書き用の仕組みは、今回の再構築で独自に追加し、その旨を明記したものです。
• HASDATA_API_KEY（任意）— 設定すると、すべての上流リクエストに呼び出し元自身のHasData APIキーを指定するx-api-key: <key>ヘッダーが付与されます。設定されていない場合、キーのヘッダーは送信されません。ヘッダー名と環境変数名は、元のレジストリ記録に記載されているものです。この環境変数からキーを転送する仕組みは、今回の再構築で独自に追加し、その旨を明記したものです。元のツール群はキーなしで取得されました。

転送の仕組み

最初のツール呼び出し時に、クライアントは上流サーバーとのストリーミング可能な HTTP セッションを開始します。まず JSON-RPC の initialize リクエスト（protocolVersion 2025-03-26、 clientInfo name mapsdata）を送信し、続いて notifications/initialized 通知を送り、その後、呼び出し元の引数を 変更せずに含めた tools/call リクエストを送信します。上流サーバーが Mcp-Session-Id ヘッダーを付けて initialize に応答すると、 その値はセッションの後続のすべてのリクエストに含まれ、プロセスの 存続期間中は同じセッションが再利用されます。応答は通常の JSON または サーバー送信イベントとして届く場合があり、どちらも読み取られます。

上流サーバーからの成功結果は、上流サーバーが設定した isError フラグも含め、 そのまま転送されます。失敗（JSON-RPC エラー、2xx 以外のステータス、 読み取り不能な応答、または完了できないリクエスト）は、 テキストが mapsdata error: で始まる isError の結果として返されます （この表示は、この再構築版独自のラベル付き再現です）。

CLI

各ツールは、1 つの JSON 引数文字列を受け取るサブコマンドとしても実行できます。

npx @reneturcios/mapsdata hasdata_google_maps_search_performMapSearch '{"q":"coffee near Union Square","hl":"en"}'
npx @reneturcios/mapsdata hasdata_google_maps_place_getPlaceDetails '{"placeId":"ChIJN1t_tDeuEmsRUsoyG83frY4"}'
npx @reneturcios/mapsdata --version

終了コード：成功時は 0、isError の結果の場合は 1、使用方法に誤りがある場合は 2 です。

MCP サーバー

npx -y @reneturcios/mapsdata mcp

MCP クライアントの設定：

{
  "mcpServers": {
    "mapsdata": {
      "command": "npx",
      "args": ["-y", "@reneturcios/mapsdata", "mcp"]
    }
  }
}

Docker

docker run -i ghcr.io/cloudcorprecords/mapsdata
docker run --rm ghcr.io/cloudcorprecords/mapsdata --version

コンテナの既定のコマンドは mcp です。そのため、最初の形式では stdio MCP サーバーとして動作し、それ以外の引数は通常どおり CLI に渡されます。

開発

npm install
npm run build
npm test
npm run dev

テストスイートはすべて、スタブ化された JSON-RPC 上流サーバーに対して実行されます。実際のネットワーク呼び出しは行いません。

ライセンス

MIT — LICENSE を参照してください。