google-maps-harness

에이전트를 위한 13개의 읽기 전용 Google Maps Platform 도구: 장소의 위치, 주변에 무엇이 있는지, 이동 시간, 도착 시의 상태.

이 저장소에서 두 가지 방법으로 설치할 수 있습니다:

동일한 기능과 동일한 제어 방식을 제공합니다. Skill이 존재하는 이유는 claude.ai가 로컬 서버를 실행할 수 없기 때문이며, MCP 서버는 로컬 프로세스가 적합한 환경에 더 잘 맞기 때문에 존재합니다.

여기서는 쓰기 작업이 없으므로, 이 도구가 관리하는 위험은 손상이 아닌 비용, 컨텍스트, 그리고 Google이 반환하는 정보에 대한 신뢰입니다.

에이전트가 얻는 것

compute_route_matrix는 조회보다는 결정을 위해 만들어진 도구입니다. 한 번의 호출로 모든 후보를 모든 옵션과 비교하여 순위를 매기고, 한 번의 청구서가 발생합니다.

Skill은 동일한 열세 가지를 하위 명령어(geocode, search-nearby, matrix)로 노출하며, 자체 설정을 진단하는 check 명령어도 포함합니다.

Related MCP server: Google Maps MCP Server Enhanced

1단계 — Google Cloud (두 경로 모두 필요)

API 활성화

Maps APIs → API list에서 결제가 활성화된 프로젝트에서 다음 API를 활성화하세요. Maps Platform은 무료 월별 크레딧 내에서도 결제 계정이 연결되지 않으면 모든 요청을 거부합니다.

특히 **Places API (New)**를 주의하세요. 콘솔에는 레거시 "Places API"도 나열되어 있으며, 그것만 활성화하면 네 개의 장소 도구 모두에서 403 오류가 발생합니다.

도달 가능하게 하려는 API만 활성화하세요. API가 꺼진 도구는 해당 API 이름을 명시하는 메시지와 함께 거부되며, 이는 의도적으로 더 작은 표면을 운영하는 좋은 방법입니다.

키 생성 및 제한

Maps Platform credentials에서 API 키를 생성하고 페이지를 떠나기 전에 두 가지 제한을 설정하세요:

• 애플리케이션 제한 → 없음. 이 키는 브라우저나 휴대폰이 아닌 서버 측 프로세스에서 사용됩니다. HTTP 리퍼러 및 Android/iOS 제한은 모두 실패합니다.

• API 제한 → 키 제한, 위의 API만 정확히 선택합니다. 제한되지 않은 키는 프로젝트의 모든 Google API에 대해 청구되므로, 유출된 키는 제한된 계정이 아닌 열린 계정이 됩니다.

각 API의 할당량 페이지에서 일일 할당량 상한도 설정하세요. Google은 자체 경계에서 이를 적용하며, 클라이언트에서 무엇이 실행되든 지출 상한이 유지되는 유일한 곳입니다.

2a단계 — Skill로 설치

패키지 빌드

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

두 가지 빌드가 있습니다. claude.ai에는 키를 보관할 곳이 없기 때문입니다. 설정할 환경도 없고 영구적인 홈 디렉토리도 없으므로, 업로드된 키 파일은 한 번의 대화 동안만 유지됩니다. 개인 빌드는 키를 Skill 내부에 번들로 포함하며, 한 번 업로드하면 유지됩니다.

이 편의성은 실제 노출입니다. 키는 Anthropic의 표준 보존 정책에 따라 Skill 아티팩트에 저장됩니다. 따라서 두 가지는 주의가 아닌 메커니즘에 의해 분리됩니다. 다른 파일 이름, 개인 빌드 자체의 SKILL.md에 있는 공유 금지 배너, 작성된 모든 위치에서 gitignored되는 *-personal.zip, 그리고 작업 트리에 키가 있어도 공유 가능한 빌드에 키가 도달하지 않음을 확인하는 tests/test_skill_build.py.

claude.ai에 설치

1. Settings → Capabilities → Skills, zip 파일 업로드.

2. Settings → Capabilities → Code execution → Domain allowlist, 다음 여섯 개 추가:

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

2단계는 선택 사항이 아니며 사람들을 당황하게 만드는 부분입니다. 샌드박스는 허용된 도메인만 허용하는 관리형 프록시를 통해 인터넷에 연결됩니다. 기본 설정(Package managers only)에서는 키가 아무리 좋아도 모든 Maps 호출이 CONNECT 터널에서 403 오류로 동일하게 실패합니다.

여섯 개의 명명된 호스트가 All domains보다 낫습니다. 이 허용 목록은 모델이 작성한 코드를 실행하는 샌드박스와 공개 인터넷 사이의 유일한 장벽이며, 하나의 Skill을 수정하기 위해 모든 것을 허용하도록 확장하는 것은 쉽게 되돌릴 수 없는 제어권을 소비하는 것입니다. 도메인별 목록은 조직 수준 기능입니다. 요금제가 전부 아니면 전무만 제공한다면, 그것이 당신 앞에 놓인 트레이드오프입니다.

샌드박스가 스크립트가 무시할 프록시를 통해 라우팅하는 경우 --use-proxy를 추가하거나 GOOGLE_MAPS_USE_PROXY=1을 설정하세요. Why --use-proxy exists를 참조하세요.

Claude Code에 설치

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

전체 네트워크 액세스, 허용 목록 필요 없음.

확인

Claude에게 Skill의 검사를 실행하도록 요청하거나 직접 실행하세요:

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
...

외부에서 동일하게 보이는 세 가지 실패(키 없음, 경로 없음, 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 파일을 읽지 않으므로 우연히 로드되는 일이 없습니다.

코드를 변경한 후 클라이언트를 다시 시작하세요. 등록된 프로세스는 시작 시 모듈을 로드하며, 그렇지 않으면 이전 코드를 계속 실행합니다.

구성

키를 제외한 모든 설정은 선택 사항입니다. Skill은 명령줄 플래그와 동일한 선택 사항을 사용합니다. python3 scripts/maps.py --help에 전체 목록이 있습니다.

비용 제어

Google은 요청당 청구하며, Places는 요청하는 가장 비싼 필드를 기준으로 청구합니다. 에이전트와 청구서 사이에는 세 가지 제어 장치가 있습니다.

• 세부 정보 계층이 가격을 결정합니다. 모든 Places 도구는 detail을 사용합니다: essentials(주소 및 좌표), pro(이름 및 비즈니스 상태 추가), enterprise(영업 시간, 평점, 전화번호, 웹사이트 추가), atmosphere(리뷰 추가). 에이전트는 계층을 지정하고 필드 마스크를 직접 구성하지 않으므로 조용히 모든 것을 요청할 수 없습니다.

• atmosphere 계층은 기본적으로 꺼져 있습니다. 가장 비싼 계층이면서 낯선 사람이 작성한 산문을 모델의 컨텍스트로 가져오는 계층입니다. 의도적으로 켜거나 전혀 사용하지 마세요.

• 모든 호출에는 상한선이 있습니다. 25개의 업스트림 요청과 30초입니다. 각 결과는 upstream_requests를 보고하므로 호출에 소비된 내용이 청구 콘솔뿐만 아니라 답변에도 표시됩니다.

compute_route_matrix는 Google 자체 625개보다 훨씬 적은 100개의 출발지-목적지 쌍으로 제한됩니다. Google은 매트릭스를 쌍별로 청구하기 때문입니다.

보안 태세

• 키는 한 곳에 보관됩니다. 전송만 키를 첨부합니다. 어떤 도구나 다른 모듈도 키를 처리하지 않습니다. Skill은 또한 명령줄 인수로 키를 받지 않습니다. argv는 ps를 통해 볼 수 있고 셸 기록에 남기 때문입니다.

• 전송된 어떤 것도 리디렉션될 수 없습니다. 리디렉션은 완전히 거부되며 모든 소켓이 열리기 전에 호스트 허용 목록이 확인됩니다. 이 API 중 세 개는 키를 쿼리 문자열에 포함하므로, 리디렉션을 따르면 청구 가능한 자격 증명이 낯선 사람에게 넘어갑니다.

• 모든 오류는 정리됩니다. 키는 클라이언트가 구축되기 전에 등록되며, 도구를 떠나는 모든 예외는 먼저 정리기를 통과합니다.

• Google이 반환하는 모든 것은 신뢰할 수 없는 것으로 표시됩니다. 장소 이름, 편집 요약, 리뷰 및 경로 안내는 비즈니스 소유자와 일반인이 작성합니다. 모든 응답에는 모델에게 해당 텍스트를 데이터로 취급하라는 경고가 포함되며, 모든 문자열은 먼저 제어 문자가 제거됩니다.

• 모든 인수는 요청이 되기 전에 검증됩니다. 좌표는 유한해야 합니다. JSON 파서는 허용하면 NaN을 전달합니다. 장소 ID는 문자 클래스와 일치한 다음 URL 경로로 퍼센트 인코딩됩니다. 자유 텍스트는 길이가 제한되고 제어 문자를 거부합니다.

• 응답은 두 번 제한됩니다. 소켓에서 4MiB, 모델의 컨텍스트로 96KiB.

--use-proxy가 존재하는 이유

프록시 환경 변수는 기본적으로 무시됩니다. 일반적인 머신에서 이 기본값은 키를 보호합니다. 이러한 변수 중 하나는 모든 요청을 다른 사람이 선택한 호스트를 통해 라우팅합니다.

샌드박스는 이를 반전시킵니다. 관리형 송신 프록시가 유일한 출구인 경우, 이를 무시하는 것은 아무것도 보호하지 않습니다. 어떤 요청도 나가지 않음을 보장합니다. 따라서 선택은 가정이 아닌 명시적이며, 필요로 하는 환경이 그것을 알고 있기 때문에 기본적으로 꺼져 있습니다.

그것이 켜져 있어도 두 가지는 여전히 유지됩니다: 호스트 허용 목록은 URL이 생성되기 전에 실행되므로 코드가 새로운 목적지로 유도될 수 없으며, CONNECT 터널은 프록시가 요청에 개입하지 못하게 합니다. 자체 인증 기관으로 TLS를 종료하는 프록시는 키를 볼 수 있습니다 — 동일한 당사자가 이미 코드를 실행하고 있는 관리형 샌드박스에서는 그렇지만, 가정하기보다는 알아두는 것이 좋습니다.

이것이 의도적으로 하지 않는 것

• 쓰기 없음. Google Maps Platform은 여기서 의미 있는 쓰기 표면이 없으며, 이것은 아무것도 노출하지 않습니다.

• 호출자가 제공하는 필드 마스크 없음. 필드 마스크는 HTTP 헤더 값입니다. 모델 출력에서 조합하면 첫 번째 개행 문자를 기다리는 헤더 인젝션이 되며, 모든 호출에서 가장 비용이 많이 드는 필드를 요청하는 방법이 됩니다.

• 로컬 지출 원장 없음. Google의 자체 API별 일일 한도는 에지에서 예산을 시행하며, 이는 클라이언트에서 무엇이 실행되든 관계없이 유지됩니다. 이를 로컬에서 복제하면 상태, 잠금 및 두 번째 숫자를 추가로 유지해야 합니다.

• 지도 이미지 또는 정적 타일 없음. 그것들은 모델이 읽을 수 없는 바이트이며, 그 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.