google-maps-mcp

A TypeScript Model Context Protocol (MCP) server that exposes Google Maps Platform APIs as tools for LLMs. Gives AI assistants real, structured map data — directions, transit routes, place search, address validation, photos, elevation, and more — instead of guessing from training data.

Works with Claude Desktop and any other MCP-compatible client.

---

Features

15 tools across three categories:

| Category | Tools | |----------|-------| | Maps | Static map image URL, embed URL (iframe), elevation data, Street View image URL | | Routes | Turn-by-turn directions (drive/walk/cycle/transit), distance matrix, multi-stop route optimization | | Places | Geocoding / reverse geocoding, place details, text search, nearby search, autocomplete, photos, address validation, timezone |

Transport: HTTP Streamable (stateful sessions, SSE keep-alive) — the modern MCP transport, compatible with mcp-remote and all HTTP-capable clients.

Minimal footprint: only two runtime dependencies (@modelcontextprotocol/sdk, zod). All Google Maps calls use Node.js built-in fetch against REST APIs — no Google SDK required.

---

Prerequisites

• Node.js 22+ (or Docker)
• mcp-remote — install once globally: npm install -g mcp-remote
• A Google Maps Platform API key with the relevant APIs enabled (see below)
• A Google Cloud project with billing enabled

APIs to enable in Google Cloud Console

Go to APIs & Services → Library and enable:

| API | Used by | |-----|---------| | Maps Static API | maps_static_map | | Street View Static API | maps_street_view | | Maps Embed API | maps_embed_url | | Elevation API | maps_elevation | | Geocoding API | places_geocode | | Time Zone API | places_timezone | | Places API (New) | places_details, places_text_search, places_nearby_search, places_autocomplete, places_photos | | Address Validation API | places_address_validation | | Routes API | routes_compute, routes_matrix | | Route Optimization API | routes_optimize (optional) |

You can restrict the key to these APIs and to your server's IP for production use.

---

Quick Start

Option A — Run with Docker (recommended)

docker run -d \
  --name google-maps-mcp \
  -p 127.0.0.1:3003:3003 \
  -e GOOGLE_MAPS_API_KEY=your_key_here \
  -e MCP_AUTH_TOKEN=your_secret_token \
  ghcr.io/apurvaumredkar/google-maps-mcp:latest

Verify:

curl http://localhost:3003/health
# {"status":"ok","service":"google-maps-mcp"}

Option B — npm / npx

No install required — run directly with npx:

GOOGLE_MAPS_API_KEY=your_key_here \
MCP_AUTH_TOKEN=your_secret_token \
npx mcp-server-google-maps
# google-maps-mcp listening on port 3003

Or install globally:

npm install -g mcp-server-google-maps
GOOGLE_MAPS_API_KEY=your_key_here MCP_AUTH_TOKEN=your_secret_token mcp-server-google-maps

Set PORT= to change the default port (3003).

---

Option C — Build from source

git clone https://github.com/apurvaumredkar/google-maps-mcp.git
cd google-maps-mcp
npm install
npm run build

Create a .env file (or export the vars):

GOOGLE_MAPS_API_KEY=your_key_here
MCP_AUTH_TOKEN=your_secret_token
# Optional — only needed for routes_optimize:
GOOGLE_CLOUD_PROJECT_ID=your_project_id

Start the server:

GOOGLE_MAPS_API_KEY=... MCP_AUTH_TOKEN=... npm start
# google-maps-mcp listening on port 3003

Option D — Docker Compose (self-hosted stack)

Add to your docker-compose.yml:

services:
  google-maps-mcp:
    build: .
    container_name: google-maps-mcp
    restart: unless-stopped
    ports:
      - "127.0.0.1:3003:3003"
    environment:
      - GOOGLE_MAPS_API_KEY=${GOOGLE_MAPS_API_KEY}
      - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
      - GOOGLE_CLOUD_PROJECT_ID=${GOOGLE_CLOUD_PROJECT_ID:-}

---

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | GOOGLE_MAPS_API_KEY | Yes | Your Google Maps Platform API key | | MCP_AUTH_TOKEN | No | Secret token clients must send in the X-Api-Key header. Omit for local-only use; set when exposing the server over a network or proxy. Generate with openssl rand -hex 32 | | PORT | No | HTTP port (default: 3003) | | GOOGLE_CLOUD_PROJECT_ID | No | Required only for routes_optimize (Route Optimization API) |

---

Connecting a Client

This server works with any MCP-compatible client — Claude Desktop, LM Studio, Cursor, or any other tool that supports the Model Context Protocol. The config format may differ per client, but the endpoint and auth are the same.

The server exposes a single endpoint: POST/GET http://localhost:3003/mcp

If MCP_AUTH_TOKEN is set, all requests must include the header:

X-Api-Key: <MCP_AUTH_TOKEN>

If MCP_AUTH_TOKEN is not set, no header is required (suitable for local-only use).

Claude Desktop (example)

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:3003/mcp",
        "--header",
        "X-Api-Key: your_secret_token"
      ]
    }
  }
}

---

Tool Reference

Maps

maps_static_map — Static Map Image

Returns a direct image URL for a static map.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | center | string | required | Address or lat,lng | | zoom | integer | 13 | Zoom level 0–21 | | size | string | 640x480 | Image dimensions WxH in pixels | | maptype | enum | roadmap | roadmap | satellite | terrain | hybrid | | markers | string | — | Marker spec e.g. color:red\|48.8566,2.3522 | | path | string | — | Path spec for drawing routes | | format | enum | png | png | jpg | gif | | scale | enum | 1 | 1 = standard, 2 = HiDPI/retina | | language | string | — | BCP 47 language code for labels | | region | string | — | ISO 3166-1 alpha-2 region code |

---

maps_embed_url — Maps Embed URL

Returns an iframe-ready embed URL.

| Parameter | Type | Description | |-----------|------|-------------| | mode | enum | place | directions | search | view | streetview | | q | string | Place/search query (place, search modes) | | center | string | lat,lng for view/streetview mode | | zoom | integer | Zoom level | | origin / destination | string | For directions mode | | waypoints | string | Pipe-separated waypoints | | maptype | enum | roadmap | satellite |

---

maps_elevation — Elevation Data

Returns elevation in metres above sea level.

| Parameter | Type | Description | |-----------|------|-------------| | locations | string | Pipe-separated lat,lng pairs | | path | string | Pipe-separated lat,lng path | | samples | integer | Number of samples along path (2–512) |

---

maps_street_view — Street View Image

Returns a direct Street View panorama image URL.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | location | string | — | Address or lat,lng | | pano | string | — | Specific panorama ID (overrides location) | | size | string | 640x480 | Image size WxH | | heading | number | — | Camera heading 0–360° | | pitch | number | — | Camera pitch -90° to 90° | | fov | number | 90 | Field of view 10–120° | | source | enum | — | outdoor to exclude indoor panoramas |

---

Routes

routes_compute — Compute Route

Turn-by-turn directions with real-time traffic.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | origin | string | required | Address or lat,lng | | destination | string | required | Address or lat,lng | | travel_mode | enum | DRIVE | DRIVE | WALK | BICYCLE | TRANSIT | TWO_WHEELER | | intermediates | string[] | — | Waypoints between origin and destination | | departure_time | string | — | ISO 8601 datetime for traffic-aware routing | | avoid_tolls | boolean | false | Avoid toll roads | | avoid_highways | boolean | false | Avoid highways | | avoid_ferries | boolean | false | Avoid ferries | | units | enum | METRIC | METRIC | IMPERIAL | | compute_alternative_routes | boolean | false | Return up to 3 alternatives |

---

routes_matrix — Route Distance Matrix

Compute travel time/distance between multiple origins and destinations simultaneously.

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | origins | string[] | required | Up to 25 addresses or lat,lng strings | | destinations | string[] | required | Up to 25 addresses or lat,lng strings | | travel_mode | enum | DRIVE | DRIVE | WALK | BICYCLE | TRANSIT | | departure_time | string | — | ISO 8601 datetime | | units | enum | METRIC | METRIC | IMPERIAL |

---

routes_optimize — Optimize Multi-Stop Route

Optimizes stop order to minimize total travel. Requires GOOGLE_CLOUD_PROJECT_ID.

| Parameter | Type | Description | |-----------|------|-------------| | vehicle_start | string | Start location — must be lat,lng (geocode first if needed) | | vehicle_end | string | End location (defaults to start) | | visits | object[] | Array of { address, label?, duration_minutes? } — addresses must be lat,lng | | travel_mode | enum | DRIVING | WALKING |

---

Places

places_geocode — Geocode / Reverse Geocode

Convert addresses ↔ coordinates.

| Parameter | Type | Description | |-----------|------|-------------| | address | string | Address to geocode | | latlng | string | lat,lng for reverse geocoding | | region | string | ISO 3166-1 alpha-2 re