google-maps-harness
Provides read-only tools for querying Google Maps data, including geocoding addresses, searching for places, retrieving place details, computing routes with traffic, getting time zone information, elevation data, air quality, and address validation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@google-maps-harness How long does it take to drive from Union Square to SFO right now?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
google-maps-harness
Thirteen read-only Google Maps Platform tools for an agent: where a place is, what is around it, how long it takes to get there, and what the conditions are when it arrives.
Two ways to install it, both from this repo:
For | Setup | |
Skill | claude.ai and Claude Code | Upload a zip. Needs a domain allowlist entry on claude.ai. |
(MCP) Model Context Protocol server | Claude Code, Claude Desktop | A venv and one registration command. |
They expose the same capability with the same controls. The Skill exists because claude.ai cannot launch a local server; the MCP server exists because it is the better fit where a local process is fine.
Nothing here writes, so the risk this manages is not damage — it is cost, context, and trust in what Google returns.
What an agent gets
Tool | Answers |
| Where is this address, landmark, or plus code? |
| What is at this coordinate? |
| Where exactly is this place id? |
| Is this address real and deliverable? |
| Which places match "ramen near Union Square"? |
| What is inside this circle, by category? |
| Hours, rating, price, phone, website for one place. |
| What did the user probably mean? |
| How long from A to B, with traffic? |
| Which of these ten is nearest to which of those ten? |
| What time is it there, right now or on a given date? |
| How high is this point, or this profile of points? |
| What is the air like there, and who should be careful? |
compute_route_matrix is the one built for deciding rather than looking up: one call ranks every candidate against every option, and one bill.
The Skill exposes the same thirteen as subcommands — geocode, search-nearby, matrix — plus a check command that diagnoses its own setup.
Related MCP server: Google Maps MCP Server Enhanced
Step 1 — Google Cloud (both paths need this)
Enable the APIs
Enable these at Maps APIs → API list on a project with billing on. Maps Platform refuses every request without a billing account attached, even inside the free monthly credit.
API | Tools it unlocks |
Geocoding API |
|
Places API (New) | the four |
Routes API |
|
Time Zone API |
|
Elevation API |
|
Address Validation API |
|
Air Quality API |
|
Watch for Places API (New) specifically — the console also lists a legacy "Places API", and enabling only that one produces a 403 on all four place tools.
Enable only what you want reachable. A tool whose API is off refuses with a message naming it, which is a fine way to run a smaller surface deliberately.
Create and restrict the key
At Maps Platform credentials, create an API key and set both restrictions before leaving the page:
Application restrictions → None. This key is used by a server-side process, not a browser or a phone. HTTP-referrer and Android/iOS restrictions all fail for it.
API restrictions → Restrict key, ticking exactly the APIs above. An unrestricted key bills for every Google API on the project, so a leaked one is an open account rather than a capped one.
Set a daily quota cap on each API's Quotas page too. Google enforces that at its own edge, which is the only place a spend cap holds no matter what runs on the client.
Step 2a — Install as a Skill
Build the package
python3 skill/build.py # dist/google-maps.zip — no credential
python3 skill/build.py --with-key .env # also dist/google-maps-personal.zipTwo builds, because claude.ai has nowhere to keep a key: no environment to set and no persistent home, so an uploaded key file lasts one conversation. The personal build bundles the key inside the Skill, which is uploaded once and stays.
Build | Contains | Upload to |
| no credential | anyone you share it with |
| your key | your own account, only |
That convenience is a real exposure — the key then lives in the Skill artifact under Anthropic's standard retention — so the two are kept apart by machinery rather than by care: different filenames, a do-not-share banner in the personal build's own SKILL.md, *-personal.zip gitignored wherever it is written, and tests/test_skill_build.py asserting no key reaches the shareable build even when one is sitting in the working tree.
Install on claude.ai
Settings → Capabilities → Skills, upload the zip.
Settings → Capabilities → Code execution → Domain allowlist, add these six:
geocode.googleapis.com places.googleapis.com routes.googleapis.com addressvalidation.googleapis.com airquality.googleapis.com maps.googleapis.com
Step 2 is not optional and is the one that catches people. The sandbox reaches the internet through a managed proxy that allows only listed domains; on the default setting (Package managers only) every Maps call fails identically with a 403 on the CONNECT tunnel, no matter how good the key is.
Six named hosts beat All domains. That allowlist is the only thing between a sandbox running model-written code and the open internet, and widening it to everything to fix one Skill spends a control you do not get back cheaply. Per-domain lists are an organization-level feature; if your plan only offers all-or-nothing, that is the trade in front of you.
If the sandbox routes through a proxy the script would otherwise ignore, add --use-proxy (or set GOOGLE_MAPS_USE_PROXY=1). See Why --use-proxy exists.
Install in Claude Code
cp -R skill/google-maps ~/.claude/skills/Full network access, nothing to allowlist.
Verify
Ask Claude to run the Skill's check, or run it yourself:
python3 skill/google-maps/scripts/maps.py check --allKEY 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
...It separates the three failures that look identical from outside — no key, no route, and an API switched off — and prints no part of the key.
Step 2b — Install as an MCP server
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_KEYclaude mcp add google-maps -- /absolute/path/to/.venv/bin/google-maps-harness --env-file /absolute/path/to/.envThe key goes in the file, not on that command line. A value passed with -e lands in ~/.claude.json and in your shell history, and neither is owner-only. The server never reads a .env it was not pointed at, so nothing loads by accident.
Restart the client after changing the code — the registered process loads its modules at startup and will otherwise keep running the old ones.
Configuration
Every setting is optional except the key. The Skill takes the same choices as command-line flags; python3 scripts/maps.py --help lists them.
Variable | Default | What it does |
| — | Required. The Maps Platform key. |
|
| Connect and read timeout per request. |
|
| Upstream requests one tool call may make. |
|
| Wall clock one tool call may spend upstream. |
| unset | Two-letter region that breaks ties on ambiguous names. |
|
| Language for place names and route instructions. |
|
| Lets place lookups request reviews and editorial summaries. |
|
| Skill only. Route through the proxy the environment names. |
Controlling what this costs
Google bills per request, and Places bills by the most expensive field you ask for. Three controls sit between an agent and your bill.
The detail tier picks the price. Every Places tool takes
detail:essentials(address and coordinates),pro(adds names and business status),enterprise(adds hours, ratings, phone, website),atmosphere(adds reviews). The agent names a tier and never composes a field mask, so it cannot quietly ask for everything.The
atmospheretier is off by default. It is both the most expensive tier and the one that pulls prose strangers wrote into the model's context. Turn it on deliberately or not at all.Every call has a hard ceiling. Twenty-five upstream requests and thirty seconds. Each result reports
upstream_requests, so what a call spent is visible in the answer rather than only in the billing console.
compute_route_matrix is capped at 100 origin-destination pairs, well under Google's own 625, because Google bills the matrix per pair.
Security posture
The key is held in one place. Only the transport attaches it. No tool, and no other module, ever handles it. The Skill additionally refuses to take it as a command-line argument, because argv is visible through
psand lands in shell history.Nothing sent can be redirected. Redirects are refused outright and the host allowlist is checked before every socket opens. Three of these APIs carry the key in the query string, so a followed redirect would hand a billable credential to a stranger.
Every error is scrubbed. The key is registered before any client is built, and every exception leaving a tool passes through the scrubber first.
Everything Google returns is labelled untrusted. Place names, editorial summaries, reviews, and route instructions are written by business owners and by the public. Every response carries a warning telling the model to treat that text as data, and every string is stripped of control characters first.
Every argument is validated before it becomes a request. Coordinates must be finite — a JSON parser will hand you
NaNif you let it. Place ids are matched against a character class and then percent-encoded into the URL path. Free text is length-capped and refuses control characters.Responses are bounded twice: 4 MiB off the socket, 96 KiB into the model's context.
Why --use-proxy exists
Proxy environment variables are ignored by default. On an ordinary machine that default protects the key: one such variable would route every request through a host somebody else chose.
A sandbox inverts it. Where a managed egress proxy is the only way out, ignoring it does not protect anything — it guarantees no request ever leaves. So the choice is explicit rather than assumed, and it stays off by default because the environment that needs it knows it does.
Two things still hold with it on: the host allowlist runs before any URL is built, so the code cannot be talked into a new destination, and a CONNECT tunnel keeps the proxy out of the request. A proxy that terminates TLS with its own certificate authority would see the key — in a managed sandbox that is the same party already running the code, but worth knowing rather than assuming.
What this deliberately does not do
No writes. Google Maps Platform has no meaningful write surface here, and this exposes none.
No caller-supplied field masks. A field mask is an HTTP header value; assembled from model output it is a header injection waiting for the first newline, and a way to ask for the most expensive fields on every call.
No local spend ledger. Google's own per-API daily caps enforce a budget at its edge, which holds regardless of what runs on the client. Duplicating that locally would add state, a lock, and a second number to keep true.
No map images or static tiles. They are bytes a model cannot read, and their URLs carry the key.
Where it runs
Surface | Skill | MCP server |
Claude Code | yes, full network | yes |
Claude Desktop | — | yes |
claude.ai | yes, once the domains are allowlisted | no — cannot launch a local process |
Claude API container | no — no network access, not configurable | no |
Development
.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 .Tests run offline. Nothing in the suite opens a socket or needs a real key — the fake transport records what a request would have been, which is what lets a test assert on the wire rather than on a mock's call count.
The Skill targets Python 3.9 while the server targets 3.11, because a Skill ships into sandboxes this project does not choose. CI runs the Skill on 3.9 for exactly that reason: a linter once rewrote timezone.utc to the 3.11-only datetime.UTC, and the suite — which runs on 3.11 and 3.14 — could not see it.
Licence
MIT.
Available Tools
13 toolsautocomplete_placesARead-only
Complete a partial place name or address into up to five candidates, each with a place id. Use this to pin down what the user meant before spending a search or a details lookup, and to turn a vague name into an id the other tools can use. The cheapest way to resolve a place.
Inputs: partial_text (required), latitude, longitude, radius_metres. Returns: object
compute_routeARead-only
Get the driving, walking, cycling, or transit route between two places, with total time, distance, and any warnings. Each endpoint is written one of three ways: 'place_id:ChIJ...' from a place search (most precise), '40.7580,-73.9855' as a coordinate pair, or plain text for Google to resolve as an address. Traffic is included on DRIVE and TWO_WHEELER. Set include_steps only when you need turn-by-turn text; it makes the response much larger.
Inputs: origin (required), destination (required), units, avoid_tolls, +7 more. Returns: object
compute_route_matrixARead-only
Get travel time and distance for every origin against every destination in one call — the comparison tool. Use it to pick the nearest branch, rank candidate sites by drive time, or check which of several suppliers is reachable inside a window. Each endpoint uses the same three forms as compute_route. Google bills this per pair, so origins times destinations is capped at 100.
Inputs: origins (required), destinations (required), avoid_tolls, travel_mode, +3 more. Returns: object
geocode_addressARead-only
Turn an address, a landmark name, or a plus code into coordinates, a normalized address, and its component parts (street, city, postal code, country). Use this before any tool that needs a latitude and longitude. Returns several candidates when the text is ambiguous.
Inputs: address (required), region_code. Returns: object
geocode_place_idARead-only
Look up the coordinates, normalized address, and address components of a place id returned by a place search. More precise than geocoding the place's name, and cheaper than a full details lookup when location is all you need.
Inputs: place_id (required). Returns: object
get_air_qualityARead-only
Get current air quality at a coordinate: the local and universal air quality index, the dominant pollutant and its concentration, and health guidance for the general population and for sensitive groups. Needs the Air Quality API enabled on the project, which is separate from the other Maps APIs.
Inputs: latitude (required), longitude (required). Returns: object
get_elevationARead-only
Get the elevation in metres above sea level at one point or at several. Pass coordinates as a list of 'lat,lng' strings, at most 50. Use it to judge terrain — how much a route climbs, whether a site is on a floodplain, how exposed a location is.
Inputs: coordinates (required). Returns: object
get_place_detailsARead-only
Read everything Google holds about one place: address, coordinates, opening hours, rating, price level, phone, and website. Takes a place id from a search or autocomplete. Set detail to control cost — enterprise is the tier that carries hours, ratings, and contact details; atmosphere adds reviews and may be disabled.
Inputs: place_id (required), detail. Returns: object
get_time_zoneARead-only
Get the time zone in force at a coordinate: its IANA id, its name, and its offset from UTC including daylight saving. Pass the moment you care about, because the offset changes across the year. Use this before reasoning about whether somewhere is open, or what local time a meeting lands at.
Inputs: latitude (required), longitude (required), timestamp (required). Returns: object
reverse_geocodeARead-only
Turn a latitude and longitude into the addresses at that point, from the exact street address outward to the neighbourhood, city, and country. Use this to describe where a coordinate is.
Inputs: latitude (required), longitude (required). Returns: object
search_places_by_textARead-only
Search for places by describing them in words — 'ramen near Union Square', 'hardware stores in Asheville NC', 'EV charging on I-81'. Returns up to 20 places per page and a token for the next page, to a maximum of 60 places. Set detail to control how much you get back and what it costs: essentials (address and coordinates), pro (adds names and business status), enterprise (adds ratings, hours, phone, and website), atmosphere (adds reviews and summaries; may be disabled).
Inputs: query (required), detail, rank_by, latitude, +6 more. Returns: object
search_places_nearbyARead-only
List places inside a circle, ranked by popularity or by distance from its centre. Use this when you have a point and want what is around it; use search_places_by_text when you can describe what you want. Up to 20 places, no paging. Filter by type with values such as restaurant, pharmacy, gas_station, hospital, or park.
Inputs: latitude (required), longitude (required), detail, rank_by, +3 more. Returns: object
validate_addressARead-only
Check whether a postal address is real and deliverable, and get back the corrected, standardized version plus a note of anything that was missing, unconfirmed, or inferred. Use this before relying on an address a user typed; use geocode_address instead when you only need coordinates.
Inputs: region_code (required), address_lines (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools have clearly distinct purposes: geocoding tools separate address, coordinate, and place ID lookups; search tools differ by text query vs. nearby; compute_route vs. compute_route_matrix are well-differentiated. However, search_places_by_text and search_places_nearby could overlap in some use cases (e.g., 'restaurants near me' vs. a point), and the descriptions partially compensate.
Tool names follow a consistent verb_noun pattern throughout (e.g., geocode_address, search_places_by_text, compute_route, get_place_details). All names are descriptive and predictable, making it easy to infer what each tool does from its name alone.
With 13 tools, the set is well-scoped for a Google Maps MCP server. Each tool covers a distinct geographic or mapping function—geocoding, search, routing, elevation, time zone, air quality, validation—without unnecessary bulk. The count feels complete and not overwhelming.
The server covers a comprehensive set of mapping operations: geocoding (forward, reverse, place ID, validation), place search (text, nearby, autocomplete, details), routing (single and matrix), and supplemental data (elevation, time zone, air quality). A minor gap is the lack of a tool for displaying maps or static map images, but this is not core to the MCP paradigm.
Maintenance
Related MCP Connectors
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
Routing, geocoding, places, matrix and map tools for location-aware AI workflows.
The Google Maps MCP server is a fully-managed server provided by the Maps Grounding Lite API that connects AI applications to Google Maps Platform services. It provides three main tools for building LLM applications: searching for places, looking up weather information, and computing routes with details like distance and travel time. The server acts as a proxy that translates Google Maps data into a format that AI applications can understand, enabling agents to accurately answer real-world location and travel queries.
Search and read published GoVisit destination and local business data through 22 read-only tools.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables location-aware AI agents to search for nearby places, get detailed place information including hours and ratings, and calculate routes with turn-by-turn directions using Google Maps APIs.22MIT
- AlicenseBqualityBmaintenanceProvides 14 comprehensive tools for geocoding, navigation, and visual mapping using Google Maps APIs. It also offers detailed environmental data including weather forecasts, air quality indices, and solar irradiance for location-based analysis and trip planning.1410MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to access Google Maps services including places search, details, directions, geocoding, and nearby search through natural language.628 PyPI3MIT
- AlicenseAqualityDmaintenanceProduction-ready MCP server for Google Maps Platform APIs, providing 11 tools for directions, places, geocoding, traffic, and road data to empower AI agents with location intelligence.1124 PyPI4Apache 2.0