google-maps-harness

Trece herramientas de solo lectura de Google Maps Platform para un agente: dónde está un lugar, qué hay a su alrededor, cuánto se tarda en llegar y cuáles son las condiciones cuando llega.

Dos formas de instalarlo, ambas desde este repositorio:

Ambos exponen la misma capacidad con los mismos controles. El Skill existe porque claude.ai no puede iniciar un servidor local; el servidor MCP existe porque es la opción más adecuada cuando un proceso local es aceptable.

Nada de esto escribe, por lo que el riesgo que gestiona no es daño — es costo, contexto y confianza en lo que Google devuelve.

Lo que obtiene un agente

compute_route_matrix es la herramienta diseñada para decidir en lugar de consultar: una llamada clasifica cada candidato frente a cada opción, y una factura.

El Skill expone las mismas trece como subcomandos — geocode, search-nearby, matrix — más un comando check que diagnostica su propia configuración.

Related MCP server: Google Maps MCP Server Enhanced

Paso 1 — Google Cloud (ambas rutas lo necesitan)

Habilitar las APIs

Habilítalas en Maps APIs → Lista de APIs en un proyecto con facturación activada. Maps Platform rechaza cada solicitud sin una cuenta de facturación adjunta, incluso dentro del crédito mensual gratuito.

Presta atención a Places API (Nueva) específicamente — la consola también lista una "Places API" heredada, y habilitar solo esa produce un 403 en las cuatro herramientas de lugares.

Habilita solo lo que quieras que sea accesible. Una herramienta cuya API está desactivada se niega con un mensaje que la nombra, lo cual es una buena manera de ejecutar una superficie más pequeña deliberadamente.

Crear y restringir la clave

En Credenciales de Maps Platform, crea una clave de API y establece ambas restricciones antes de salir de la página:

• Restricciones de aplicación → Ninguna. Esta clave es utilizada por un proceso del lado del servidor, no por un navegador o un teléfono. Las restricciones de referente HTTP y Android/iOS fallan para ella.

• Restricciones de API → Restringir clave, marcando exactamente las APIs anteriores. Una clave sin restricciones factura por cada API de Google en el proyecto, por lo que una filtrada es una cuenta abierta en lugar de una limitada.

Establece también un límite de cuota diaria en la página de Cuotas de cada API. Google lo aplica en su propio borde, que es el único lugar donde un límite de gasto se mantiene sin importar lo que se ejecute en el cliente.

Paso 2a — Instalar como Skill

Construir el paquete

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

Dos compilaciones, porque claude.ai no tiene dónde guardar una clave: no hay entorno que configurar ni un home persistente, por lo que un archivo de clave subido dura una conversación. La compilación personal empaqueta la clave dentro del Skill, que se sube una vez y permanece.

Esa conveniencia es una exposición real — la clave entonces vive en el artefacto del Skill bajo la retención estándar de Anthropic — por lo que las dos se mantienen separadas por mecanismos en lugar de por cuidado: diferentes nombres de archivo, un banner de no compartir en el propio SKILL.md de la compilación personal, *-personal.zip en gitignore dondequiera que se escriba, y tests/test_skill_build.py que afirma que ninguna clave llega a la compilación compartible incluso cuando una está en el árbol de trabajo.

Instalar en claude.ai

1. Configuración → Capacidades → Skills, sube el zip.

2. Configuración → Capacidades → Ejecución de código → Lista de dominios permitidos, añade estos seis:

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

El paso 2 no es opcional y es el que atrapa a la gente. El sandbox llega a internet a través de un proxy gestionado que solo permite dominios listados; en la configuración predeterminada (Solo gestores de paquetes) cada llamada a Maps falla idénticamente con un 403 en el túnel CONNECT, sin importar lo buena que sea la clave.

Seis hosts nombrados superan a Todos los dominios. Esa lista de permitidos es lo único que hay entre un sandbox que ejecuta código escrito por el modelo e internet abierto, y ampliarla a todo para arreglar un Skill gasta un control que no se recupera fácilmente. Las listas por dominio son una característica a nivel de organización; si tu plan solo ofrece todo o nada, esa es la compensación que tienes delante.

Si el sandbox enruta a través de un proxy que el script ignoraría de otro modo, añade --use-proxy (o establece GOOGLE_MAPS_USE_PROXY=1). Consulta Por qué existe --use-proxy.

Instalar en Claude Code

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

Acceso completo a la red, nada que añadir a la lista de permitidos.

Verificar

Pídele a Claude que ejecute la verificación del Skill, o ejecútala tú mismo:

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

Separa los tres fallos que parecen idénticos desde fuera — sin clave, sin ruta y una API desactivada — y no imprime ninguna parte de la clave.

Paso 2b — Instalar como servidor 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

La clave va en el archivo, no en esa línea de comandos. Un valor pasado con -e termina en ~/.claude.json y en el historial de tu shell, y ninguno es solo del propietario. El servidor nunca lee un .env al que no se le haya señalado, por lo que nada se carga por accidente.

Reinicia el cliente después de cambiar el código — el proceso registrado carga sus módulos al inicio y, de lo contrario, seguirá ejecutando los antiguos.

Configuración

Toda configuración es opcional excepto la clave. El Skill acepta las mismas opciones como banderas de línea de comandos; python3 scripts/maps.py --help las lista.

Controlar lo que esto cuesta

Google factura por solicitud, y Places factura por el campo más caro que solicites. Tres controles se interponen entre un agente y tu factura.

• El nivel de detalle fija el precio. Cada herramienta de Places acepta detail: essentials (dirección y coordenadas), pro (añade nombres y estado del negocio), enterprise (añade horario, calificaciones, teléfono, sitio web), atmosphere (añade reseñas). El agente nombra un nivel y nunca compone una máscara de campo, por lo que no puede pedir silenciosamente todo.

• El nivel atmosphere está desactivado por defecto. Es tanto el nivel más caro como el que introduce prosa escrita por desconocidos en el contexto del modelo. Actívalo deliberadamente o no lo hagas.

• Cada llamada tiene un límite máximo. Veinticinco solicitudes ascendentes y treinta segundos. Cada resultado informa upstream_requests, por lo que lo que gasta una llamada es visible en la respuesta en lugar de solo en la consola de facturación.

compute_route_matrix está limitada a 100 pares origen-destino, muy por debajo de los 625 de Google, porque Google factura la matriz por par.

Postura de seguridad

• La clave se mantiene en un solo lugar. Solo el transporte la adjunta. Ninguna herramienta, y ningún otro módulo, la maneja jamás. El Skill además se niega a aceptarla como argumento de línea de comandos, porque argv es visible a través de ps y termina en el historial del shell.

• Nada enviado puede ser redirigido. Las redirecciones se rechazan directamente y la lista de dominios permitidos se verifica antes de abrir cada socket. Tres de estas APIs llevan la clave en la cadena de consulta, por lo que una redirección seguida entregaría una credencial facturable a un extraño.

• Cada error se depura. La clave se registra antes de construir cualquier cliente, y cada excepción que sale de una herramienta pasa primero por el depurador.

• Todo lo que Google devuelve está etiquetado como no confiable. Los nombres de lugares, resúmenes editoriales, reseñas e instrucciones de ruta están escritos por propietarios de negocios y por el público. Cada respuesta lleva una advertencia que le dice al modelo que trate ese texto como datos, y cada cadena se limpia de caracteres de control primero.

• Cada argumento se valida antes de convertirse en una solicitud. Las coordenadas deben ser finitas — un analizador JSON te dará NaN si lo permites. Los ids de lugar se comparan con una clase de caracteres y luego se codifican como porcentaje en la ruta URL. El texto libre tiene un límite de longitud y rechaza caracteres de control.

• Las respuestas están limitadas dos veces: 4 MiB del socket, 96 KiB en el contexto del modelo.

Por qué existe --use-proxy

Las variables de entorno de proxy se ignoran por defecto. En una máquina ordinaria, ese valor predeterminado protege la clave: una de esas variables enrutaría cada solicitud a través de un host que alguien más eligió.

Un sandbox lo invierte. Donde un proxy de salida gestionado es la única salida, ignorarlo no protege nada — garantiza que ninguna solicitud salga jamás. Por lo tanto, la elección es explícita en lugar de asumida, y permanece desactivada por defecto porque el entorno que la necesita sabe que la necesita.

Dos cosas siguen siendo válidas con él activado: la lista de permitidos de host se ejecuta antes de que se construya cualquier URL, por lo que no se puede engañar al código para que vaya a un nuevo destino, y un túnel CONNECT mantiene el proxy fuera de la solicitud. Un proxy que termina TLS con su propia autoridad de certificación vería la clave — en un sandbox gestionado que es la misma parte que ya ejecuta el código, pero vale la pena saberlo en lugar de asumirlo.

Lo que esto deliberadamente no hace

• Sin escrituras. Google Maps Platform no tiene una superficie de escritura significativa aquí, y esto no expone ninguna.

• Sin máscaras de campo proporcionadas por el llamante. Una máscara de campo es un valor de cabecera HTTP; ensamblada a partir de la salida del modelo es una inyección de cabecera esperando el primer salto de línea, y una forma de solicitar los campos más costosos en cada llamada.

• Sin libro de gastos local. Los límites diarios por API de Google imponen un presupuesto en su borde, que se mantiene independientemente de lo que se ejecute en el cliente. Duplicar eso localmente añadiría estado, un bloqueo y un segundo número que mantener verdadero.

• Sin imágenes de mapa ni teselas estáticas. Son bytes que un modelo no puede leer, y sus URLs llevan la clave.

Dónde se ejecuta

Desarrollo

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

Las pruebas se ejecutan sin conexión. Nada en el conjunto abre un socket ni necesita una clave real — el transporte falso registra lo que habría sido una solicitud, que es lo que permite a una prueba afirmar en el cable en lugar de en el recuento de llamadas de un mock.

El Skill está dirigido a Python 3.9 mientras que el servidor está dirigido a 3.11, porque un Skill se envía a sandboxes que este proyecto no elige. CI ejecuta el Skill en 3.9 exactamente por esa razón: un linter reescribió una vez timezone.utc al datetime.UTC solo de 3.11, y el conjunto — que se ejecuta en 3.11 y 3.14 — no pudo verlo.

Licencia

MIT.