maps-mcp

A Model Context Protocol server for Google Maps — routing, place discovery, and commute comparison over stdio.

Tools

get_transit_commute

Route between two addresses (or neighborhoods). Supports transit (default), driving, walking, bicycling, two_wheeler. Multi-leg trips via intermediates (A→B→C). Returns up to 3 alternative routes, each with:

• mode, duration_minutes, distance_km, summary, steps_count
• transit: segments (line + vehicle type), transfers, walking_minutes, first_departure, last_arrival
• driving / two_wheeler: duration_in_traffic_minutes (traffic-aware), toll_roads

search_places

Find restaurants, hotels, attractions, parks, gas stations, etc. using free-text queries. Optionally bias by location (near), filter by place type (type), and filter to currently-open places (open_now). Returns up to 20 results with name, address, rating, price level, open/closed status, and a id for follow-up.

get_place_details

Full details for a place from search_places: phone, website, per-day opening hours, editorial summary, and up to 5 user reviews. Takes a place_id.

compare_commutes

Rank 2–5 candidate origins against a shared destination by travel time. Fans out in parallel and returns results sorted fastest → slowest. Per-origin failures surface inline rather than aborting the whole comparison.

Google Cloud setup

In Google Cloud Console, pick or create a project and enable these APIs (APIs & Services → Library):

• Routes API — for get_transit_commute and compare_commutes
• Places API (New) — for search_places and get_place_details

Then Credentials → Create credentials → API key. Restrict the key to those two APIs. Put the value in .env:

echo 'GOOGLE_MAPS_API_KEY=your-key-here' > .env

Setup & running

npm install
npm run build
npm start          # or: npx tsx src/index.ts  (dev, no build needed)

Make target	What it does
make install	npm ci
make build	Compile TypeScript → dist/
make dev / make start	Run server (dev / compiled)
make test	Unit + in-memory e2e tests
make test-live	Live API test (needs key)
make smoke	One real API request
make docker-build / make docker-run	Build/run Docker image

Connecting a client (e.g. Cursor / Claude Desktop)

{
  "mcpServers": {
    "maps-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/maps-mcp/dist/index.js"],
      "env": { "GOOGLE_MAPS_API_KEY": "your-key-here" }
    }
  }
}

For dev without building: "command": "npx", "args": ["tsx", "/absolute/path/to/maps-mcp/src/index.ts"].

Notes

• MCP server name: google-maps-transit
• driving and two_wheeler use TRAFFIC_AWARE routing (Routes API v2)
• Up to MAX_ROUTES = 3 alternatives returned; Google may return fewer
• Missing GOOGLE_MAPS_API_KEY surfaces as a clear tool error