@aiwerk/mcp-server-google-maps

Google Maps Platform MCP server — places, geocoding, turn-by-turn directions, route matrices, elevation and time zones.

Built on the current Google APIs: Places API (New), Routes API v2, Geocoding API, Elevation API and Time Zone API. Turn-by-turn steps, transit routes and live traffic are included, which the Maps Grounding Lite MCP service does not provide.

Install

npx -y @aiwerk/mcp-server-google-maps

Or add to your MCP client config:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@aiwerk/mcp-server-google-maps"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key"
      }
    }
  }
}

Configure

| Variable | Required | Description | |---|---|---| | GOOGLE_MAPS_API_KEY | yes | API key from Google Cloud Console | | GOOGLE_MAPS_API_TIMEOUT_MS | no | Request timeout in ms (default: 30000) |

APIs to enable on the Cloud project

Each tool group calls a different API, and a disabled API answers REQUEST_DENIED or HTTP 403. Enable the ones you plan to use:

| API | Powers | |---|---| | Places API (New) | maps_search_places, maps_search_nearby, maps_place_details, maps_place_autocomplete | | Geocoding API | maps_geocode, maps_reverse_geocode, maps_place_id_lookup | | Routes API | maps_directions, maps_distance_matrix | | Elevation API | maps_elevation | | Time Zone API | maps_timezone |

Billing must be enabled on the project. The legacy Places API and Directions API are not used, so enabling those alone is not enough.

Tools

11 read-only tools. Nothing in this server writes, and every tool is annotated readOnlyHint.

| Name | Description | |---|---| | maps_search_places | Text search for places, with optional area bias, type, rating, price and open-now filters. | | maps_search_nearby | Places inside a circle around a coordinate, with the radius as a hard restriction. | | maps_place_details | Full detail for one place ID: hours, phone, website, rating, optionally reviews. | | maps_place_autocomplete | Place suggestions plus place IDs for partially typed input. | | maps_geocode | Address to coordinates, with normalised address components and place ID. | | maps_reverse_geocode | Coordinates to the addresses at that point. | | maps_place_id_lookup | Place ID to address and coordinates through the cheaper Geocoding API. | | maps_directions | Route with turn-by-turn steps, waypoints, traffic, alternatives and transit support. | | maps_distance_matrix | Travel time and distance for every origin-destination pair. | | maps_elevation | Elevation for up to 100 points, or a sampled profile along a path. | | maps_timezone | Time zone, UTC offset and DST offset for a coordinate at a given moment. |

Location arguments

maps_directions and maps_distance_matrix accept three shapes for every location:

| Shape | Example | |---|---| | Address | "Bundesplatz 3, 3005 Bern" | | Coordinates | "46.9480,7.4474" | | Place ID | "place_id:ChIJ..." |

maps_reverse_geocode, maps_elevation and maps_timezone need coordinates, since those APIs do not geocode. Run maps_geocode first.

Cost control

Places and Routes calls are billed by the fields they request, so the field masks in this server are deliberately narrow.

• maps_place_details leaves reviews out until you set include_reviews: true, which moves the call to the Enterprise + Atmosphere tier.
• maps_directions requests turn-by-turn steps by default. Set include_steps: false for totals only.
• maps_search_places and maps_search_nearby accept a fields array that replaces the default mask entirely, for either trimming cost or reaching fields the default omits.
• maps_place_id_lookup resolves a place ID through Geocoding instead of Place Details when only the address is needed.

Set a quota cap in Google Cloud Console before pointing an autonomous agent at this server.

Notes

• The classic web services (Geocoding, Elevation, Time Zone) answer HTTP 200 even when they refuse a request, with the real result in a status field. This server checks that field, so a bad key surfaces as a tool error instead of an empty success.
• ZERO_RESULTS is returned as data, not as an error. An empty results array means the address or route genuinely has no match.
• routingPreference and the avoid_* flags only apply to DRIVE and TWO_WHEELER. Passing them with WALK, BICYCLE or TRANSIT is rejected locally rather than sent to the API.
• maps_distance_matrix results carry originIndex and destinationIndex and are not necessarily ordered.

License

MIT