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

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

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