maps-mcp

An MCP server exposing Google Maps Platform to any MCP client: geocoding, place search/details, traffic-aware travel times, and time zones. Seven tools, built on the Python MCP SDK (FastMCP). Runs as a local stdio server or as a containerized Streamable HTTP service with bearer auth.

Auth is a single API key, not OAuth — Maps Platform is a key-metered developer API, so there are no accounts to connect and no token refresh.

Tool Reference

Tool	Parameters	Description
geocode	address, region = ""	Free-form address/place name → coordinates, canonical address, place_id. region is a ccTLD bias (e.g. au; default from MAPS_REGION).
reverse_geocode	latitude, longitude	Coordinates → nearest street address(es).
place_search	query, latitude = 0, longitude = 0, radius_meters = 0, open_now = False, max_results = 5	Text search for businesses/POIs ("vet near Potts Point"). Returns name, address, rating, open-now, phone, place_id. Optional circular location bias (default radius 5 km when a point is given).
place_details	place_id	One place in full: weekly opening hours, phone, website, rating, price level, editorial summary.
travel_time	origin, destination, mode = "drive", departure_time = "", avoid_tolls = False, arrival_time = "", include_tolls = False	Route duration + distance via the Routes API; traffic-aware for drive/two_wheeler (reports delay vs no-traffic baseline). Transit answers include per-leg detail (line, stops, clock times) and accept arrival_time ("be there by") — transit only, per the API. include_tolls adds an estimated toll cost for driving modes (extra computation, off by default). departure_time RFC3339, now-or-future.
place_search_nearby	latitude, longitude, included_types = "", radius_meters = 1500, max_results = 5, rank_by_distance = False	Typed "what's around me" (Places New searchNearby): included_types is a comma-separated place-type list (pharmacy, restaurant,cafe); optional nearest-first ranking.
time_zone	latitude, longitude, timestamp = 0	IANA zone + UTC offset (incl. DST) at a point; timestamp (epoch) evaluates DST at that moment.

Origins/destinations for travel_time accept three spellings, resolved by shape: a free-form address, "lat,lng", or "place_id:<id>".

# "When do I need to leave?" — compose with your calendar MCP server
travel_time(
    origin="home address here",
    destination="325 Edgecliff Rd, Woollahra",   # from the event's location
    mode="drive",
    departure_time="2026-07-05T08:30:00+10:00",
)

# Find somewhere that's open right now
place_search(query="pharmacy Potts Point", open_now=True)

Setup (Google Cloud console — one-time)

1. Create (or pick) a GCP project. Prefer a dedicated project — an API key is easier to leak than an OAuth token, and project isolation caps the blast radius. Enable billing (personal volumes sit inside the monthly free tiers, but the billing account is mandatory).
2. Enable four APIs: Geocoding API, Places API (New), Routes API, Time Zone API.
3. Create an API key (Credentials → Create credentials → API key) and restrict it to exactly those four APIs. Add IP restrictions if the caller set is stable.
4. Set MAPS_API_KEY in the server's environment and restart. The server runs fine without the key — every tool call returns a setup-pointer error until it's set — so deployment order doesn't matter.

Quick start (stdio)

Most MCP clients (Claude Code, Claude Desktop, VS Code, …) spawn stdio servers directly. With uv installed:

// e.g. Claude Desktop claude_desktop_config.json / Claude Code .mcp.json
{
  "mcpServers": {
    "maps": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/maps-mcp", "maps-mcp", "--stdio"],
      "env": { "MAPS_API_KEY": "your-key-here" }
    }
  }
}

stdio mode has no network surface and skips bearer auth — the client owns the process.

HTTP mode (container)

The bundled Containerfile builds a Streamable HTTP server at /mcp (stateless — restarts never strand client sessions). HTTP mode refuses to start without MCP_BEARER_TOKEN; clients authenticate with Authorization: Bearer <token>.

podman build -t maps-mcp .    # or: docker build -t maps-mcp .
podman run -d --name maps-mcp -p 8328:8328 \
  -e MAPS_API_KEY=your-key -e MCP_BEARER_TOKEN=some-long-random-token \
  maps-mcp

maps_mcp.healthcheck does a full HTTP round-trip to /mcp (the 401 counts as alive — it proves the event loop responds); wire it to your container healthcheck with a restart-on-unhealthy policy. Terminate TLS at a reverse proxy — the server itself speaks plain HTTP.

Configuration

Env var	Default	Purpose
MAPS_API_KEY	(empty)	Google Maps Platform API key. Tools error clearly when unset.
MAPS_REGION	(empty)	Optional ccTLD geocoding bias (e.g. au). Empty lets Google decide.
MAPS_LANGUAGE	(empty)	Optional BCP-47 language for Places responses (e.g. en-AU).
PORT	8328	HTTP listen port.
MCP_BEARER_TOKEN	(empty)	Required in HTTP mode; server refuses to start without it. Not used in --stdio mode.

Architecture notes

• Four upstream APIs, one thread-safe httpx.Client. Legacy-style APIs (Geocoding, Time Zone) take the key as a query param and report errors in a body status field; new-style APIs (Places New, Routes) take X-Goog-Api-Key + a mandatory X-Goog-FieldMask header.
• Sync tool handlers are offloaded to a worker thread (the MCP SDK runs sync tools inline on the event loop, so a slow upstream call would otherwise stall every concurrent request). Per-request log lines (tool= outcome= duration_ms= rss_mib=) go to stderr.
• API-key values are redacted from error messages before they can reach logs or clients.

Testing

# Tiers 1 + 2 — pure helpers + mocked HTTP (fast, no network, no key)
uv run --extra test pytest tests/test_maps_client.py -v

# Tier 3 — live API round-trips against stable Sydney landmarks
# (read-only; nothing to clean up). Gated on the key; skips without it.
MAPS_API_KEY=... uv run --extra test pytest tests/test_integration.py -v

License

MIT