# @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

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

Or add to your MCP client config:

```json
{
  "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](https://console.cloud.google.com/apis/credentials) |
| `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