MCP Google Map Server

AI エージェント向け Google Maps

AI アプリごとに場所検索、ルート案内、位置情報のワークフローを作り直すのはもうやめましょう。

@cablate/mcp-google-map は Google Maps Platform を、読み取り専用の 18 個のエージェントツールと、用途を絞った 3 つのスキルに変換します。エージェントは MCP またはスタンドアロン CLI を通じて、実在する場所の検索、ルートの確認、候補の比較、実用的な旅程の作成、ローカル検索での表示状況の監査を行えます。

利用する統合方式を選べます。MCP のセットアップなしでスキルを使いたい場合は Codex または Claude Code Plugin、デスクトップ MCP クライアントには stdio、共有デプロイやリモートデプロイには Streamable HTTP を利用できます。

英語 · 繁体字中国語

選ぶ理由

エージェントに Maps API をそのまま渡すのは、始まりにすぎません。有用な回答を得るには、場所を特定し、その識別情報を保持し、周辺を検索し、営業時間の詳細を確認し、移動時間を計算し、実際に確認した内容を説明するなど、複数の依存する呼び出しが必要になることがよくあります。このプロジェクトは、そうした作業を一貫したインターフェースにまとめています。

• 検索から成果につなげます。 基本ツールでジオコーディング、場所の詳細、ルート案内、天気、空気質、地図を扱えます。複合ツールでは、エリアの探索、候補の比較、立ち寄り先の最適化、ローカル検索順位の測定ができます。
• MCP の有無にかかわらず、同じ機能を使えます。 スタンドアロンの exec CLI はエージェントスキルや自動化で利用でき、MCP サーバーは stdio または HTTP 経由で同じ 18 個のツールを公開します。
• 関数名だけでなく、ワークフローの指針もエージェントに提供します。 3 つのスキルで、一般的な地図調査、根拠に基づく旅行計画、ローカル SEO を扱います。Codex はリクエストに該当する場合にのみ、スキルの指示全文を読み込みます。
• デプロイと認証情報を自分で管理できます。 ローカルで実行することも、セルフホストすることもできます。API キーは環境またはリクエストヘッダー内に保持され、HTTP デプロイではセッションごとに分離されます。
• 必要なものから始めて、後から拡張できます。 GOOGLE_MAPS_ENABLED_TOOLS で必要なツールだけを登録するか、カタログ全体を利用できます。

エージェントでできること

成果	プロジェクトによる支援
実在する場所を検索して評価する	自然言語検索と周辺検索、場所の詳細、評価、営業時間、口コミ、距離の比較
地理的に無理のない旅行を計画する	候補の検索、ルート沿いの立ち寄り先、移動時間の確認、複数の立ち寄り先の最適化、天気、静的地図
近隣エリアを調査する	複数カテゴリの探索に加え、距離、標高、タイムゾーン、天気、空気質を対象を絞って確認
現地作業や配送を計画する	最大 25 か所のルート行列と、最適化された立ち寄り順序
ローカル検索での表示状況を監査する	地理的なグリッドでの順位、競合の検索、ARP、ATRP、SoLV 指標
位置情報を充実させる	単一または一括のジオコーディング、逆ジオコーディング、構造化された JSON 出力

これらはデータと計画のためのツールであり、安全性、アクセシビリティ、営業状況、順位の結果を保証するものではありません。Places の口コミ、写真、AI 要約を表示するアプリケーションは、コンテンツの帰属表示と保存に関するガイダンスに従う必要があります。

統合方法を選ぶ

用途	最適な対象	実行されるもの
Codex Plugin	MCP の設定なしで、Codex に地図、旅行、ローカル SEO に関する質問をする	該当する Skill が必要に応じて読み込まれ、スタンドアロン CLI を呼び出します
Claude Code Plugin	Claude マーケットプレイスから同じ 3 つの Skill をインストールする	Skill は mcp-google-map 名前空間の下に配置され、スタンドアロン CLI を呼び出します
スタンドアロン CLI	スクリプト、自動化、その他の Skill 対応エージェント	ステートレスなコマンド 1 つで JSON を返します
MCP stdio	Claude Desktop、Cursor、VS Code、その他のローカル MCP クライアント	クライアントがローカル MCP プロセスを起動します
Streamable HTTP	マルチセッション、コンテナー化環境、LAN、またはリモートアクセス	セルフホスト可能なサーバーが /mcp を公開します

すべての方法で Node.js 22+ と Google Maps Platform API キーが必要です。ライブ呼び出しには料金が発生する場合があります。選択したツールに必要な API を有効にしてください。一般的な場所検索や経路検索のワークフローでは、Places API (New)、Routes API、および多くの場合 Geocoding API が必要です。

Codex を使って始める — MCP は不要

codex plugin marketplace add cablate/mcp-google-map --ref main
codex plugin add mcp-google-map@cablate

Codex の実行環境で GOOGLE_MAPS_API_KEY を設定し、新しい会話を開始します。Google API リクエストを送信せずにローカルのセットアップを確認します。

npx -y @cablate/mcp-google-map doctor

成功すると、node、package、api-key のチェックに合格し、live-api はスキップされます。Geocoding、Places、Routes に料金が発生する可能性のあるチェックを送信する場合に限り、doctor --live を使用してください。

次のように質問してみてください。

京都で実用的な 2 日間の旅程を計画してください。近くの場所をまとめ、移動時間を確認し、営業時間に関する前提があれば説明してください。

Codex は、一般的な場所の調査には google-maps、旅程の作成には google-maps-travel-planning、ビジネスの認知度分析には google-maps-local-seo を選択します。このプラグインは MCP サーバーを登録または起動しません。再現可能な例については、MCP を使わない手順を参照してください。

Claude Code にインストールする — MCP は不要

claude plugin marketplace add cablate/mcp-google-map
claude plugin install mcp-google-map@cablate-maps

新しい Claude Code セッションを開始し、その環境で GOOGLE_MAPS_API_KEY を設定して、上記と同じ doctor チェックを実行します。Claude では、インストール済みの Skill がプラグインの名前空間付きで表示されます。たとえば /mcp-google-map:google-maps-travel-planning です。

各 GitHub リリースには、バージョン付きの mcp-google-map-claude-plugin-v*.zip と、直接配布用の SHA-256 チェックサムも含まれています。リリースワークフローでは、同じ skills/ ソースからこのアーカイブをビルドし、公開前に Claude Code 公式の厳格なバリデーターで検証します。

スタンドアロン CLI を使う

すべての MCP ツールには、短縮 CLI 名も用意されています。

npx -y @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx -y @cablate/mcp-google-map exec search-places '{"query":"quiet cafes in Kyoto"}'
npx -y @cablate/mcp-google-map exec directions '{"origin":"Tokyo Station","destination":"Tokyo Skytree","mode":"transit"}'

各呼び出しはステートレスです。成功した呼び出しは標準出力に { "success": true, "data": ... } を返します。失敗した呼び出しは 0 以外の終了コードで終了し、構造化 JSON を標準エラー出力に書き込みます。

住所データを一括で補完するには、次のようにします。

npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -

MCP クライアントを接続する

stdio

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@cablate/mcp-google-map", "--stdio"],
      "env": { "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY" }
    }
  }
}

ツール一覧によるコンテキストの消費を抑えるには、"GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places" のように、カンマ区切りの許可リストを追加します。すべてのツールを公開するには、この設定を省略するか * を指定します。

Streamable HTTP

npx @cablate/mcp-google-map --host 127.0.0.1 --port 3000 --apikey "YOUR_API_KEY"

{
  "mcpServers": {
    "google-maps": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

サーバーが外部接続を受け入れる必要がある場合に限り、0.0.0.0 にバインドしてください。マルチテナントのデプロイでは、キーをセッションごとに分離できるよう、X-Google-Maps-API-Key リクエストヘッダーを使用することをおすすめします。

ツール一覧

グループ	ツール
場所と検索	maps_search_places、maps_search_nearby、maps_place_details、maps_explore_area、maps_compare_places、maps_search_along_route
位置情報と経路検索	maps_geocode、maps_reverse_geocode、maps_directions、maps_distance_matrix、maps_plan_route、maps_batch_geocode
コンテキストと可視化	maps_elevation、maps_timezone、maps_weather、maps_air_quality、maps_static_map
ローカル SEO	maps_local_rank_tracker

18 個のツールすべてで、readOnlyHint: true および destructiveHint: false が宣言されています。正確なパラメーター、レスポンスの形式、ワークフローのレシピについては、ツールリファレンスを参照してください。

API キーと Google Cloud のセットアップ

キーは、課金が有効で、実行環境に適合する制限が設定された Google Cloud プロジェクトに属している必要があります。セットアップと診断ガイドでは、各機能に必要な API と、よくある問題について説明しています。

認証情報の優先順位は次のとおりです。

1. X-Google-Maps-API-Key HTTP リクエストヘッダー
2. --apikey コマンドラインオプション
3. GOOGLE_MAPS_API_KEY 環境変数

環境変数またはリクエストヘッダーの使用を推奨します。コマンドラインに指定したシークレットは、シェルの履歴やプロセス一覧に表示されることがあります。

信頼性と制限

• 場所やルートに関する情報は、プロジェクトで有効にした Google Maps Platform API から取得されます。天気情報の利用可能状況には地域による制限があります。
• API リクエストが正常に応答しても、アクセシビリティ、安全性、法的な適合性、リアルタイムでの利用可能性が保証されるわけではありません。
• パッケージは、返された場合にソース情報と開示に関するメタデータを保持しますが、適切な帰属表示と保存については、引き続きインターフェース側で対応する必要があります。
• HTTP モードでは、セッションごとの API キーの分離と DNS リバインディング保護に対応しています。
• このプロジェクトは MIT ライセンスで、セルフホスト可能です。脆弱性の報告については SECURITY.md を、レビュー用チェックリストについては Security Assessment Clarifications をご覧ください。

開発

git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map
npm ci
npm run build
npm run test:unit
npm test

ライブ E2E テストの実行には GOOGLE_MAPS_API_KEY が必要で、課金が発生する場合があります：npm run test:e2e。

コントリビューションを歓迎します。プルリクエストを作成する前に、CONTRIBUTING.md をお読みください。リリース履歴は CHANGELOG.md に記載されています。

謝辞

Streamable HTTP サポートの追加に協力してくださった @junyinnnn に感謝します。

ライセンス

MIT