google-maps-harness

エージェント向けの13の読み取り専用 Google Maps Platform ツール：場所の位置、周辺情報、移動時間、到着時の状況。

このリポジトリからインストールする方法は2つあります。

どちらも同じ機能を同じ制御で提供します。スキルは claude.ai がローカルサーバーを起動できないために存在します。MCP サーバーは、ローカルプロセスで問題ない場合に適しているため存在します。

このツールは書き込みを一切行わないため、管理するリスクは損害ではなく、コスト、コンテキスト、そして Google が返す情報への信頼です。

エージェントが得られるもの

compute_route_matrix は、検索ではなく判断のために作られたツールです。1回の呼び出しで、すべての候補をすべてのオプションに対してランク付けし、1回の請求になります。

スキルは同じ13個をサブコマンドとして公開します（geocode、search-nearby、matrix）。さらに、自身のセットアップを診断する check コマンドも含まれます。

Related MCP server: Google Maps MCP Server Enhanced

ステップ1 — Google Cloud（両方のパスで必要）

API を有効にする

Map API → API 一覧 で、請求先が設定されているプロジェクトに対してこれらを有効にします。Maps Platform は、無料の月間クレジットの範囲内でも、請求先アカウントが紐付いていないとすべてのリクエストを拒否します。

特に Places API (New) に注意してください。コンソールには従来の「Places API」も表示されますが、そちらだけを有効にすると、4つの場所ツールすべてで403エラーが発生します。

公開したいものだけを有効にしてください。API がオフのツールを使用すると、その名前を明示したエラーメッセージが返されるため、意図的に機能範囲を絞って運用するのに適しています。

キーを作成して制限を設定する

Maps Platform 認証情報 で、API キーを作成し、ページを離れる前に両方の制限を設定します。

• アプリケーションの制限 → なし。 このキーはブラウザやスマートフォンではなく、サーバーサイドのプロセスで使用されます。HTTP リファラー制限や Android/iOS 制限はすべて失敗します。

• API の制限 → キーを制限 し、上記の API のみにチェックを入れます。制限のないキーは、プロジェクト上のすべての Google API に対して課金されるため、漏洩すると上限のないアカウントになります。

各 API の [割り当て] ページで、1日の割り当て上限も設定してください。Google は自身のエッジでこれを強制します。これが、クライアント側で何が実行されていても支出上限を確実に守る唯一の方法です。

ステップ 2a — スキルとしてインストールする

パッケージをビルドする

python3 skill/build.py                     # dist/google-maps.zip — no credential
python3 skill/build.py --with-key .env     # also dist/google-maps-personal.zip

2つのビルドがあります。claude.ai にはキーを保存する場所がないためです。環境変数を設定する場所も、永続的なホームディレクトリもないため、アップロードされたキーファイルは1回の会話でしか持続しません。パーソナルビルドはキーをスキル内にバンドルします。これは一度アップロードすれば永続的に使用できます。

この利便性には実際のリスクが伴います。キーは Anthropic の標準的な保持ポリシーに従ってスキルアーティファクトに保存されます。そのため、2つは注意ではなく仕組みによって分離されています。異なるファイル名、パーソナルビルドの SKILL.md 内の共有禁止のバナー、*-personal.zip は書き込まれた場所で gitignore され、tests/test_skill_build.py は、ワーキングツリーにキーが存在する場合でも共有可能なビルドにキーが含まれていないことをアサートします。

claude.ai にインストールする

1. 設定 → 機能 → スキル で、zip をアップロードします。

2. 設定 → 機能 → コード実行 → ドメイン許可リスト で、次の6つを追加します。

   geocode.googleapis.com
   places.googleapis.com
   routes.googleapis.com
   addressvalidation.googleapis.com
   airquality.googleapis.com
   maps.googleapis.com

ステップ2は必須であり、見落とされがちです。サンドボックスは管理されたプロキシを通じてインターネットにアクセスし、許可されたドメインのみが通れます。デフォルト設定（パッケージマネージャーのみ）では、キーがどんなに正しくても、すべての Maps 呼び出しが CONNECT トンネルで403エラーになって失敗します。

6つの名前付きホストは すべてのドメイン よりも優れています。その許可リストは、モデルが記述したコードを実行するサンドボックスとオープンインターネットの間の唯一の防御であり、1つのスキルを修正するためにこれをすべてに拡大すると、簡単には戻せない制御を消費することになります。ドメインごとのリストは組織レベルの機能です。あなたのプランが「すべてか無か」しか提供しない場合、それがあなたの目の前にあるトレードオフです。

サンドボックスが、スクリプトが通常は無視するプロキシを経由する場合、--use-proxy を追加するか、GOOGLE_MAPS_USE_PROXY=1 を設定してください。--use-proxy が存在する理由 を参照。

Claude Code にインストールする

cp -R skill/google-maps ~/.claude/skills/

フルネットワークアクセス。許可リストは不要。

確認する

Claude にスキルのチェックを実行するよう依頼するか、自分で実行します。

python3 skill/google-maps/scripts/maps.py check --all

KEY       bundled with the skill (39 characters, fingerprint 28988599)
PROXY     none in the environment; requests go direct
NETWORK   reachable

OK  Geocoding            enabled
OK  Places (New)         enabled
...

外部からは同じに見える3つの障害（キーなし、ルートなし、API がオフ）を区別し、キーの一部は出力しません。

ステップ 2b — MCP サーバーとしてインストールする

python3 -m venv .venv
.venv/bin/pip install --require-hashes -r requirements.lock
.venv/bin/pip install -e . --no-deps
cp .env.example .env && chmod 600 .env      # then fill in GOOGLE_MAPS_API_KEY

claude mcp add google-maps -- /absolute/path/to/.venv/bin/google-maps-harness --env-file /absolute/path/to/.env

キーはそのコマンドラインではなく、ファイルに記述します。-e で渡された値は ~/.claude.json とシェル履歴に保存され、どちらも所有者のみがアクセスできるわけではありません。サーバーは指定された .env 以外は読み取らないため、誤って読み込まれることはありません。

コードを変更した後はクライアントを再起動してください。登録されたプロセスは起動時にモジュールを読み込むため、再起動しないと古いコードが実行され続けます。

設定

キー以外のすべての設定はオプションです。スキルはコマンドラインフラグとして同じ選択肢を受け取ります。python3 scripts/maps.py --help で一覧表示されます。

コストを管理する

Google はリクエストごとに課金し、Places は要求する最も高価なフィールドに基づいて課金します。エージェントと請求書の間には3つの制御があります。

• 詳細度の階層で価格が決まる。 すべての Places ツールは detail パラメータを受け取ります。essentials（住所と座標）、pro（名前と営業状況を追加）、enterprise（営業時間、評価、電話番号、ウェブサイトを追加）、atmosphere（レビューを追加）。エージェントは階層を指定し、フィールドマスクを自分で構成することはないため、こっそりとすべてを要求することはできません。

• atmosphere 階層はデフォルトでオフ。 最も高価な階層であると同時に、見知らぬ人が書いた散文をモデルのコンテキストに引き込む階層です。意図的に有効にするか、まったく使用しないでください。

• すべての呼び出しにハードリミットあり。 上流リクエスト25回、30秒。各結果は upstream_requests を報告するため、呼び出しに費やされた金額は請求コンソールだけでなく、回答にも表示されます。

compute_route_matrix は、Google 自身の625ペアを大幅に下回る100の起点-終点ペアに制限されています。Google はペアごとにマトリックスを課金するためです。

セキュリティ体制

• キーは1か所で保持。 トランスポートのみがキーを付加します。ツールやその他のモジュールがキーを扱うことはありません。スキルはさらに、キーをコマンドライン引数として受け取ることを拒否します。argv は ps で見え、シェル履歴に残るためです。

• 送信されたものをリダイレクトできない。 リダイレクトは完全に拒否され、ソケットを開く前にホスト許可リストがチェックされます。これらの API のうち3つはクエリ文字列にキーを含むため、リダイレクトに従うと、課金可能な認証情報が見知らぬ人に渡ってしまいます。

• すべてのエラーはスクラブされる。 キーはクライアントが構築される前に登録され、ツールから送出されるすべての例外は最初にスクラバーを通過します。

• Google が返すすべての情報は信頼できないとラベル付けされる。 場所の名前、編集者による概要、レビュー、ルート案内は、事業主や一般の人々によって書かれています。すべての応答には、モデルに対してそのテキストをデータとして扱うよう警告するメッセージが含まれ、すべての文字列から制御文字が削除されます。

• すべての引数はリクエストになる前に検証される。 座標は有限でなければなりません。JSON パーサーは、許可すると NaN を渡します。プレイス ID は文字クラスに対して照合され、URL パスにパーセントエンコードされます。自由テキストは長さ制限があり、制御文字を拒否します。

• 応答は二重に制限される: ソケットから最大4 MiB、モデルのコンテキストに最大96 KiB。

--use-proxy が存在する理由

プロキシ環境変数はデフォルトで無視されます。通常のマシンでは、このデフォルトがキーを保護します。そのような変数が1つあると、すべてのリクエストが他人の選択したホストを経由してしまうからです。

サンドボックスではそれが逆転します。管理された egress プロキシが唯一の出口である場合、それを無視しても何も保護されません。リクエストが決して外部に出ないことが保証されるだけです。そのため、選択は明示的に行われ、想定されるものではありません。そして、デフォルトでオフのままであるのは、それを必要とする環境が自身のことを認識しているからです。

それを有効にしても、2つのことは変わりません。ホスト許可リストはURLが構築される前に実行されるため、コードを新しい宛先に誘導することはできません。また、CONNECTトンネルによりプロキシはリクエストに関与しません。独自の認証局でTLSを終端するプロキシはキーを確認できますが、それは管理されたサンドボックス内であり、すでにコードを実行している同じ当事者です。しかし、想定するよりも知っておく価値があります。

これが意図的に行わないこと

• 書き込みはありません。 Google Maps Platformにはここで意味のある書き込み面はなく、これによって公開されるものもありません。

• 呼び出し元が指定するフィールドマスクはありません。 フィールドマスクはHTTPヘッダー値です。モデル出力から組み立てると、最初の改行を待つヘッダーインジェクションとなり、毎回の呼び出しで最も高価なフィールドを要求する方法になります。

• ローカルの支出台帳はありません。 Google自身のAPIごとの日次上限がエッジで予算を強制し、クライアントで何が実行されていても有効です。それをローカルで複製すると、状態、ロック、そして真実を保つための2番目の数値が追加されます。

• 地図画像や静的タイルはありません。 それらはモデルが読み取れないバイトであり、そのURLにはキーが含まれています。

実行環境

開発

.venv/bin/python -m unittest discover -s . -p "test_*.py"
.venv/bin/ruff check . && .venv/bin/ruff format --check . && .venv/bin/mypy --strict --exclude tests .

テストはオフラインで実行されます。スイート内の何もソケットを開いたり、実際のキーを必要としません。フェイクトランスポートはリクエストがどうなっていたかを記録し、それによりテストはモックの呼び出し回数ではなく、実際のワイヤー上でアサートできます。

SkillはPython 3.9をターゲットとし、サーバーは3.11をターゲットとしています。なぜなら、Skillはこのプロジェクトが選択しないサンドボックスに出荷されるからです。CIはまさにその理由でSkillを3.9で実行します。かつてリンターがtimezone.utcを3.11専用のdatetime.UTCに書き換え、スイート（3.11と3.14で実行される）はそれを見つけられませんでした。

ライセンス

MIT.