google-maps-harness

Тринадцать инструментов Google Maps Platform только для чтения для агента: где находится место, что вокруг него, сколько времени нужно, чтобы туда добраться, и каковы условия по прибытии.

Два способа установки, оба из этого репозитория:

Они предоставляют одинаковые возможности с одинаковыми элементами управления. Навык существует, потому что claude.ai не может запустить локальный сервер; MCP-сервер существует, потому что он лучше подходит там, где локальный процесс приемлем.

Ничто здесь не записывает, поэтому риск, которым это управляет, — не ущерб, а стоимость, контекст и доверие к тому, что возвращает Google.

Что получает агент

compute_route_matrix — это инструмент, созданный для принятия решений, а не для поиска: один вызов ранжирует каждого кандидата по каждому варианту, и один счёт.

Навык предоставляет те же тринадцать в виде подкоманд — geocode, search-nearby, matrix — плюс команда check, которая диагностирует собственную настройку.

Related MCP server: Google Maps MCP Server Enhanced

Шаг 1 — Google Cloud (оба пути требуют этого)

Включите API

Включите их в разделе Maps APIs → API list в проекте с включённым биллингом. Maps Platform откажет в любом запросе без привязанного платежного аккаунта, даже в рамках ежемесячного бесплатного кредита.

Обратите внимание на Places API (New) — в консоли также указана устаревшая «Places API», и включение только её приводит к ошибке 403 при всех четырёх инструментах для мест.

Включайте только то, что должно быть доступно. Инструмент, API которого отключён, отказывает с сообщением, содержащим его название, что является хорошим способом намеренно ограничить поверхность.

Создайте и ограничьте ключ

В разделе Maps Platform credentials создайте ключ API и установите оба ограничения, не покидая страницу:

• Application restrictions → None. Этот ключ используется серверным процессом, а не браузером или телефоном. Ограничения по HTTP-рефереру, Android/iOS для него не работают.

• API restrictions → Restrict key, отметив именно указанные выше API. Неограниченный ключ выставляет счёт за каждый API Google в проекте, поэтому утёкший ключ — это открытый аккаунт, а не ограниченный.

Также установите дневной лимит квоты на странице квот каждого API. 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

Две сборки, потому что в claude.ai негде хранить ключ: нет среды для установки и постоянного домашнего каталога, поэтому загруженный файл ключа действует только в течение одного разговора. Персональная сборка включает ключ внутрь навыка, который загружается один раз и остаётся.

Такое удобство представляет реальную угрозу — ключ затем хранится в артефакте навыка в рамках стандартного хранения Anthropic — поэтому они разделены с помощью механизмов, а не осторожности: разные имена файлов, баннер «не делиться» в собственном SKILL.md персональной сборки, *-personal.zip в gitignore везде, где он создаётся, и 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 завершается ошибкой 403 на туннеле CONNECT, независимо от того, насколько хорош ключ.

Шесть именованных хостов лучше, чем All domains. Этот список разрешённых — единственное, что отделяет песочницу, запускающую написанный моделью код, от открытого интернета, и расширение его на всё для исправления одного навыка тратит контроль, который не вернуть дёшево. Списки на домен — это функция уровня организации; если ваш план предлагает только «всё или ничего», это компромисс перед вами.

Если песочница маршрутизируется через прокси, который скрипт в противном случае проигнорировал бы, добавьте --use-proxy (или установите GOOGLE_MAPS_USE_PROXY=1). См. Почему существует --use-proxy.

Установка в Claude Code

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

Полный доступ к сети, ничего не нужно добавлять в список разрешённых.

Проверка

Попросите Клода выполнить проверку навыка или выполните её сами:

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, на который он не был указан, поэтому ничего не загружается случайно.

Перезапустите клиент после изменения кода — зарегистрированный процесс загружает модули при запуске и в противном случае будет продолжать использовать старые.

Конфигурация

Все настройки необязательны, кроме ключа. Навык принимает те же параметры в виде флагов командной строки; python3 scripts/maps.py --help выводит их.

Контроль стоимости

Google взимает плату за каждый запрос, а Places — за самое дорогое поле, которое вы запрашиваете. Между агентом и вашим счётом находятся три элемента управления.

• Уровень детализации определяет цену. Каждый инструмент Places принимает параметр detail: essentials (адрес и координаты), pro (добавляет названия и статус бизнеса), enterprise (добавляет часы работы, рейтинг, телефон, веб-сайт), atmosphere (добавляет отзывы). Агент указывает уровень и никогда не составляет маску поля, поэтому он не может незаметно запросить всё.

• Уровень atmosphere отключён по умолчанию. Он одновременно и самый дорогой, и тот, который затягивает написанные незнакомцами тексты в контекст модели. Включайте его намеренно или не включайте вообще.

• Каждый вызов имеет жёсткий предел. Двадцать пять запросов к вышестоящему сервису и тридцать секунд. Каждый результат сообщает upstream_requests, поэтому затраты на вызов видны в ответе, а не только в консоли биллинга.

compute_route_matrix ограничен 100 парами «источник-назначение», что значительно меньше собственного лимита Google в 625, поскольку Google выставляет счёт за матрицу за каждую пару.

Безопасность

• Ключ хранится в одном месте. Только транспорт его присоединяет. Ни один инструмент и ни один другой модуль никогда не обрабатывает его. Навык также отказывается принимать его в качестве аргумента командной строки, поскольку argv виден через ps и попадает в историю оболочки.

• Ничто отправленное не может быть перенаправлено. Перенаправления категорически отклоняются, а список разрешённых хостов проверяется перед каждым открытием сокета. Три из этих API передают ключ в строке запроса, поэтому выполненное перенаправление передало бы оплачиваемые учётные данные незнакомцу.

• Каждая ошибка очищается. Ключ регистрируется до создания любого клиента, и каждое исключение, покидающее инструмент, сначала проходит через очиститель.

• Всё, что возвращает Google, помечается как ненадёжное. Названия мест, редакторские сводки, отзывы и инструкции по маршруту написаны владельцами бизнеса и общественностью. Каждый ответ содержит предупреждение, говорящее модели рассматривать этот текст как данные, и каждая строка сначала очищается от управляющих символов.

• Каждый аргумент проверяется перед тем, как стать запросом. Координаты должны быть конечными — парсер JSON передаст вам NaN, если вы позволите. Идентификаторы мест проверяются на соответствие классу символов, а затем процентно кодируются в путь URL. Свободный текст ограничен по длине и отказывается принимать управляющие символы.

• Ответы ограничены дважды: 4 МиБ на сокете, 96 КиБ в контексте модели.

Почему существует --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 .

Тесты выполняются офлайн. Ничего в наборе не открывает сокет и не требует реального ключа — фиктивный транспорт записывает, каким был бы запрос, что позволяет тесту проверять передаваемые данные, а не количество вызовов мока.

Навык нацелен на Python 3.9, а сервер — на 3.11, потому что навык поставляется в песочницы, которые этот проект не выбирает. CI запускает навык на 3.9 именно по этой причине: однажды линтер переписал timezone.utc на datetime.UTC, доступный только в 3.11, и набор — который работает на 3.11 и 3.14 — не смог этого заметить.

Лицензия

MIT.