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:

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:

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

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.

#### maps_embed_url — Maps Embed URL Returns an iframe-ready embed URL.

#### maps_elevation — Elevation Data Returns elevation in metres above sea level.

#### maps_street_view — Street View Image Returns a direct Street View panorama image URL.

Routes

#### routes_compute — Compute Route Turn-by-turn directions with real-time traffic.

TRANSIT restrictions: TRANSIT mode does not support intermediates (waypoints) or route modifiers (avoid_tolls, avoid_highways, avoid_ferries). Passing these with travel_mode: TRANSIT returns a clear error — compute separate legs instead (A→B, then B→C).

#### routes_matrix — Route Distance Matrix Compute travel time/distance between multiple origins and destinations simultaneously.

#### routes_optimize — Optimize Multi-Stop Route Optimizes stop order to minimize total travel. Requires GOOGLE_CLOUD_PROJECT_ID.

Places

#### places_geocode — Geocode / Reverse Geocode Convert addresses ↔ coordinates.

#### places_details — Place Details Full details for a place by its Google Place ID.

#### places_text_search — Search Places by Text Find places matching a natural language query.

#### places_nearby_search — Search Nearby Places Find places near a coordinate within a radius.

#### places_autocomplete — Place Autocomplete Predict place names from partial input.

#### places_photos — Place Photos Get photo URLs for a place.

#### places_address_validation — Validate Address Validate and standardize a postal address.

#### places_timezone — Get Timezone Get IANA timezone and UTC/DST offset for any coordinates.

Architecture

src/
├── index.ts         # Raw Node.js HTTP server, auth, stateful session management
├── server.ts        # McpServer instantiation + tool registration
├── maps-client.ts   # Typed fetch wrappers for all Google Maps REST APIs
└── tools/
    ├── maps.ts      # 4 tools: static map, embed, elevation, street view
    ├── routes.ts    # 3 tools: compute route, matrix, optimize
    └── places.ts    # 8 tools: geocode, details, text search, nearby, autocomplete,
                     #          photos, address validation, timezone

Key design decisions:

• Raw `node:http` instead of Express — required for correct interop with the MCP SDK's internal Hono-based request handling. Express pre-consumes the request body stream in a way that breaks StreamableHTTPServerTransport.
• Stateful session map — mcp-remote and SSE keep-alive require sessions to persist across requests. Sessions are keyed by Mcp-Session-Id header and cleaned up on transport close.
• Auth before body read — the X-Api-Key check happens on the header before any body stream is touched, so rejected requests drain cleanly.
• Auth split for Google APIs — legacy REST APIs (Static Maps, Geocoding, Elevation, Timezone, Street View) use ?key= query param; new APIs (Places v1, Routes v2, Address Validation) use X-Goog-Api-Key header.

Development

npm run dev    # TypeScript watch mode (tsc --watch)
npm run build  # Compile to dist/
npm start      # Run compiled server

Rebuild Docker image after changes

docker compose build google-maps-mcp
docker compose up -d google-maps-mcp

Testing the MCP endpoint

# Health check (no auth required)
curl http://localhost:3003/health

# MCP initialize (auth required)
TOKEN=your_secret_token
curl -s -X POST http://localhost:3003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Api-Key: $TOKEN" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}},"id":1}'

# List tools (use session ID from Mcp-Session-Id response header)
SESSION=<Mcp-Session-Id from above>
curl -s -X POST http://localhost:3003/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "X-Api-Key: $TOKEN" \
  -H "Mcp-Session-Id: $SESSION" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":2}'

Windows/WSL gotcha: if your .env file has Windows CRLF line endings, extract values with tr -d '\r': ``bash TOKEN=$(grep MCP_AUTH_TOKEN .env | cut -d= -f2 | tr -d '\r') ``

Changelog

v1.0.4

• `routes_compute`: Added early validation for TRANSIT mode — passing intermediates or route modifiers (avoid_tolls, avoid_highways, avoid_ferries) now returns a clear, actionable error instead of a cryptic 400 from the Google API.

v1.0.3

• `routes_compute`: Added transit_allowed_modes parameter to filter transit routes by vehicle type (BUS, SUBWAY, TRAIN, LIGHT_RAIL, RAIL).

v1.0.2

• Initial public release with 15 tools across Maps, Routes, and Places categories.