@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