# maps-mcp

A [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://console.cloud.google.com/), 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`:

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

## Setup & running

```bash
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)

```json
{
  "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