Google Maps MCP Server

A general-purpose Google Maps MCP server: geocoding, place search, place details, directions, distance matrices, and time zone lookup over the Model Context Protocol, served over authenticated streamable HTTP.

Tools

Supported place categories: food_and_drink, entertainment_and_recreation, shopping, sports, automotive, health_and_wellness, lodging.

Directions and distance-matrix inputs accept street addresses, place names, or "lat,lng" strings.

Itinerary planning

find_nearby_places results include each place's coordinates, and its docstring teaches the calling model the walking-center pattern: recenter each follow-up search on the previously chosen stop instead of searching a whole area from one fixed center, so multi-stop plans cluster geographically. enrich_location validates that each stop is open at its planned visit time, and create_embedded_map renders the finished itinerary. The embedded map is an MCP Apps view (map_app.html) served from ui://google-maps/itinerary-map.html; hosts without MCP Apps support still get the fallback maps link. Transit itineraries render per-leg maps because the Maps Embed API does not support waypoints in transit mode.

Setup

pip install -r requirements.txt
copy .env.example .env   # then fill in real values
python server.py         # serves http://localhost:8000/mcp

.env lives next to server.py and needs:

The server refuses to start if MCP_SHARED_SECRET is unset.

Authentication

Requests to /mcp are accepted with either credential; everything else gets 401:

1. X-MCP-Secret header matching MCP_SHARED_SECRET — for Claude Code and scripts.

2. OAuth 2.1 Bearer token — for claude.ai / Claude Desktop custom connectors. The server implements the MCP authorization spec itself (metadata discovery, dynamic client registration, PKCE authorization-code flow with refresh tokens): connecting from Claude opens a consent page where you enter the shared secret once, and Claude holds tokens from then on. Tokens are stateless HMAC-signed blobs keyed off MCP_SHARED_SECRET, so they survive restarts, and rotating the secret revokes all of them. OAuth redirect targets are restricted to Claude's callback URLs and loopback addresses; extend with a comma-separated OAUTH_EXTRA_REDIRECTS env var if needed.

GET /healthz and the OAuth endpoints (/.well-known/*, /register, /authorize, /token) are the only unauthenticated routes.

Required Google Cloud APIs

Enable these in your Google Cloud project:

• Geocoding API

• Places API (New)

• Routes API (used for directions and distance matrix — the legacy Directions/Distance Matrix APIs are not available to new Google Cloud projects)

• Time Zone API

• Maps Embed API (embedded itinerary maps — free of charge, unlimited). Embed URLs expose their API key client-side; optionally set MAPS_EMBED_API_KEY to a separate HTTP-referrer-restricted key.

Cost control

The quota-sensitive endpoints are wrapped with an in-memory TTL cache plus a minimum-interval throttle (see cost_control.py):

enrich_location's web search uses keyless DuckDuckGo (ddgs); from datacenter IPs it can occasionally rate-limit, in which case that leg of the response degrades to an error field while Google data and the website extract still come back. Name-to-place_id resolution uses Text Search with an ID-only field mask, which is a free SKU.

Repeated identical calls are served from cache and never hit Google. Cheap endpoints (Geocoding, Time Zone) call the API directly. Note that every distance-matrix element (origins × destinations) is billed as a request, so the tool caps inputs at 10 origins × 10 destinations. The cache is per-process: it resets on restart, which on Render's free tier includes spin-down after idle periods.

Deploying to Render (free tier)

The repo ships a Render blueprint (free-tier Python web service).

1. Push this repo to GitHub (already done if you're reading this there).

2. In the Render dashboard, click New → Blueprint, connect the GitHub repo, and accept the defaults from render.yaml.

3. When prompted for environment variables, set GOOGLE_MAPS_API_KEY and MCP_SHARED_SECRET (generate a fresh secret for production; don't reuse your local one).

4. Deploy. Your MCP endpoint is https://<your-service>.onrender.com/mcp, and https://<your-service>.onrender.com/healthz should return {"status": "ok"} without auth.

Free-tier caveat: Render spins the instance down after ~15 minutes without inbound traffic, and the 30–60 s cold start is longer than claude.ai's connector timeout. To prevent this, the server pings its own /healthz every 10 minutes while running on Render (see start_keep_alive in server.py), keeping the instance warm around the clock. One always-on service fits within the free tier's 750 instance-hours/month.

Pushing to main auto-deploys the service.

Connecting Claude

claude.ai / Claude Desktop (custom connector, OAuth)

1. Go to Settings → Connectors → Add custom connector.

2. Enter https://<your-service>.onrender.com/mcp as the URL. Leave the Advanced settings (OAuth client ID/secret) empty — the server supports dynamic client registration.

3. Click Add, then Connect. You'll be redirected to the server's consent page: enter your MCP_SHARED_SECRET and click Authorize.

Free-tier note: if the Render service has spun down, the consent page or first connection attempt may time out while it cold-starts — retry after ~30 s.

Claude Code — either auth method works:

# Header auth (no browser round-trip):
claude mcp add --transport http google-maps \
  https://<your-service>.onrender.com/mcp \
  --header "X-MCP-Secret: <your-secret>"

# Or OAuth: add without the header, then run /mcp in a session and
# pick "Authenticate" — a browser opens the same consent page.

Project layout

Run tests with pip install -r requirements-dev.txt then python -m pytest.