225 lines
6.7 KiB
Markdown
225 lines
6.7 KiB
Markdown
# Google Maps MCP Server (gmaps)
|
||
|
||
## Overview
|
||
|
||
A Python MCP server providing **public-transit & mapping** capabilities via the Google Maps Platform APIs.
|
||
|
||
**Server name:** `gmaps`
|
||
**Transport:** `stdio` (spawns `python3 scripts/gmaps_mcp_server.py`)
|
||
**Location:** `scripts/gmaps_mcp_server.py`
|
||
|
||
---
|
||
|
||
## Tools
|
||
|
||
All tools are callable as `mcp__gmaps__<tool>`; the table lists the bare `<tool>` names.
|
||
|
||
| Tool | Required params | Optional params | Description |
|
||
|------|-----------------|-----------------|-------------|
|
||
| `status` | *(none)* | *(none)* | Self-check: verifies the API key is valid and the Geocoding API responds. Call first when another Maps tool fails. |
|
||
| `directions` | `origin`, `destination` | `mode`, `departure_time`, `transit_mode`, `transit_routing_preference`, `alternatives`, `language` | Step-by-step directions (transit, driving, walking, bicycling) |
|
||
| `geocode` | `address` | `language`, `region` | Address / place name → coordinates + place_id |
|
||
| `reverse_geocode` | `lat`, `lng` | `language` | Coordinates → formatted address |
|
||
| `search_places` | *(at least one of `query`/`location`)* | `radius`, `type`, `language` | Find nearby stations, stops, POIs |
|
||
| `distance_matrix` | `origins`, `destinations` | `mode`, `language` | Travel time & distance between multiple points |
|
||
|
||
---
|
||
|
||
## Authentication
|
||
|
||
### API Key
|
||
|
||
Unlike Gmail/Calendar (OAuth), Google Maps uses a **plain API key**.
|
||
|
||
**Priority order:**
|
||
|
||
1. Environment variable `GOOGLE_MAPS_API_KEY`
|
||
2. File `secrets/gmaps_api_key.txt` (first non-empty line)
|
||
|
||
The `secrets/` directory is in `.gitignore` — the key will not be committed.
|
||
|
||
### Required Google Cloud APIs
|
||
|
||
Enable all four in the [Google Cloud Console](https://console.cloud.google.com/apis/library):
|
||
|
||
| API | Used by |
|
||
|-----|---------|
|
||
| **Directions API** | `directions` |
|
||
| **Geocoding API** | `geocode`, `reverse_geocode` |
|
||
| **Places API** | `search_places` |
|
||
| **Distance Matrix API** | `distance_matrix` |
|
||
|
||
---
|
||
|
||
## Setup
|
||
|
||
### 1. Create API Key
|
||
|
||
1. Go to [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials)
|
||
2. Click **Create credentials → API key**
|
||
3. (Recommended) Restrict the key to the four APIs above
|
||
|
||
### 2. Save the key
|
||
|
||
```bash
|
||
echo "YOUR_API_KEY_HERE" > secrets/gmaps_api_key.txt
|
||
```
|
||
|
||
Or set the environment variable in your shell/`run.sh`:
|
||
|
||
```bash
|
||
export GOOGLE_MAPS_API_KEY=AIza...
|
||
```
|
||
|
||
### 3. Install the Python dependency
|
||
|
||
```bash
|
||
.venv/bin/pip install googlemaps
|
||
# or, if you re-run run.sh, it installs requirements.txt automatically
|
||
```
|
||
|
||
`googlemaps` is already listed in `requirements.txt`.
|
||
|
||
### 4. Register the server with the agent
|
||
|
||
Ask the agent:
|
||
```
|
||
register_mcp(
|
||
name="gmaps",
|
||
transport="stdio",
|
||
command="python3",
|
||
args=["scripts/gmaps_mcp_server.py"]
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## Usage Examples
|
||
|
||
### Self-check: is Maps working?
|
||
|
||
```
|
||
mcp__gmaps__status()
|
||
```
|
||
Returns `OK: …` if the API key is present, valid, and the Geocoding API responds; otherwise an `Error:` string explaining what to fix. Call this first whenever another Maps tool fails.
|
||
|
||
### Transit directions home (now)
|
||
|
||
```
|
||
mcp__gmaps__directions(
|
||
origin="Piazza del Duomo, Milano",
|
||
destination="casa mia", ← or the real address saved in agent memory
|
||
mode="transit"
|
||
)
|
||
```
|
||
|
||
### Prefer train, fewer transfers
|
||
|
||
```
|
||
mcp__gmaps__directions(
|
||
origin="current location",
|
||
destination="Via Roma 1, Torino",
|
||
mode="transit",
|
||
transit_mode="train",
|
||
transit_routing_preference="fewer_transfers"
|
||
)
|
||
```
|
||
|
||
### Find the nearest metro station
|
||
|
||
```
|
||
mcp__gmaps__search_places(
|
||
query="metro",
|
||
location="Piazza Garibaldi, Napoli",
|
||
radius=500,
|
||
type="subway_station"
|
||
)
|
||
```
|
||
|
||
### How long does it take from A to B?
|
||
|
||
```
|
||
mcp__gmaps__distance_matrix(
|
||
origins="Stazione Centrale, Milano",
|
||
destinations="Aeroporto Malpensa",
|
||
mode="transit"
|
||
)
|
||
```
|
||
|
||
---
|
||
|
||
## Enable / Disable
|
||
|
||
```
|
||
toggle_item(kind="mcp", id="gmaps", enabled=false) # disable
|
||
toggle_item(kind="mcp", id="gmaps", enabled=true) # re-enable
|
||
restart # required for changes to take effect
|
||
```
|
||
|
||
---
|
||
|
||
## Dependencies
|
||
|
||
| Package | Version | Purpose |
|
||
|---------|---------|---------|
|
||
| `googlemaps` | latest | Google Maps Platform Python client |
|
||
|
||
---
|
||
|
||
## Parameter notes
|
||
|
||
### Coordinates format
|
||
|
||
Whenever a parameter accepts coordinates, pass them as a **`"latitude,longitude"` decimal string with no spaces**, e.g. `"45.4654,9.1866"`. Never pass an array or separate fields.
|
||
|
||
### `departure_time`
|
||
|
||
Must be the **literal string `"now"`** or an **ISO 8601 datetime string with timezone offset**, e.g. `"2025-06-15T08:30:00+02:00"`. Never pass a Unix timestamp integer — the tool now rejects non-string values with an explicit error.
|
||
|
||
### `transit_mode`
|
||
|
||
Restricts results to a specific vehicle: `"train"` = intercity/regional rail, `"subway"` = metro, `"tram"` = trams, `"bus"` = buses, `"rail"` = any rail. Omit to allow any vehicle.
|
||
|
||
---
|
||
|
||
## Error Handling
|
||
|
||
| Error | Response |
|
||
|-------|----------|
|
||
| API key not found | `"Error: Google Maps API key not found. Set GOOGLE_MAPS_API_KEY…"` |
|
||
| `googlemaps` not installed | `"Error: Missing dependency: No module named 'googlemaps'. Run: pip install googlemaps"` |
|
||
| `OVER_QUERY_LIMIT` | `"Error: <API> API quota exceeded (OVER_QUERY_LIMIT). Check usage and billing in the Google Cloud Console."` |
|
||
| `REQUEST_DENIED` | `"Error: <API> API request denied (REQUEST_DENIED). Verify that the API key … is valid and that the <API> API is enabled …"` |
|
||
| `INVALID_REQUEST` | `"Error: <API> API rejected the request as invalid (INVALID_REQUEST). Check that the addresses, coordinates, and parameters are well-formed."` |
|
||
| `MAX_ELEMENTS_EXCEEDED` | `"Error: <API> API returned MAX_ELEMENTS_EXCEEDED — too many origins×destinations at once. …"` |
|
||
| `NOT_FOUND` | `"Error: <API> API could not geocode one of the supplied places. …"` |
|
||
| Timeout | `"Error: <API> API request timed out. Retry in a moment."` |
|
||
| No route found | `"No routes found from '…' to '…'."` |
|
||
| Missing required param | `"Error: Missing required parameter '…'"` |
|
||
| Invalid `departure_time` | `"Error: 'departure_time' must be 'now' or an ISO 8601 string …"` |
|
||
|
||
All error responses are flagged with `isError: true`. The error label `<API>` reflects which Google Maps Platform API was being called (Directions, Geocoding, Places, Distance Matrix).
|
||
|
||
All errors are logged to stderr with `[gmaps_mcp]` prefix.
|
||
|
||
---
|
||
|
||
## Protocol
|
||
|
||
Implements JSON-RPC 2.0 over stdio (same as gcal and gmail servers):
|
||
|
||
- **Requests:** read from stdin, one JSON object per line
|
||
- **Responses:** written to stdout
|
||
- **Logs:** stderr only, prefixed `[gmaps_mcp]`
|
||
|
||
Supported methods: `initialize`, `notifications/initialized`, `tools/list`, `tools/call`.
|
||
|
||
---
|
||
|
||
## When to Update This File
|
||
|
||
- New tools added
|
||
- Auth mechanism changes (e.g. OAuth migration)
|
||
- New transport option added
|
||
- Error cases change
|