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.

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':

TOKEN=$(grep MCP_AUTH_TOKEN .env | cut -d= -f2 | tr -d '\r')