mcp-google-map

• 18 tools — 14 atomic + 4 composite (explore-area, plan-route, compare-places, local-rank-tracker)
• 3 modes — stdio, StreamableHTTP, standalone exec CLI
• Agent Skill — built-in skill definition teaches AI how to chain geo tools (skills/google-maps/)

vs Google Grounding Lite

Quick Start

# stdio (Claude Desktop, Cursor, etc.)
npx @cablate/mcp-google-map --stdio

# exec CLI — no server needed
npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'

# HTTP server
npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

Special Thanks

Special thanks to @junyinnnn for helping add support for streamablehttp.

Available Tools

All tools are annotated with readOnlyHint: true and destructiveHint: false — MCP clients can auto-approve these without user confirmation.

Prerequisite: Enable Places API (New) and Routes API in Google Cloud Console before using place-related and routing tools.

Installation

Method 1: stdio (Recommended for most clients)

Works with Claude Desktop, Cursor, VS Code, and any MCP client that supports stdio:

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@cablate/mcp-google-map", "--stdio"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Reduce context usage — If you only need a subset of tools, set GOOGLE_MAPS_ENABLED_TOOLS to limit which tools are registered:

{
  "env": {
    "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY",
    "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places"
  }
}

Omit or set to * for all 18 tools (default).

Method 2: HTTP Server

For multi-session deployments, per-request API key isolation, or remote access:

npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

# Bind to all interfaces for remote access (e.g. Docker, LAN)
npx @cablate/mcp-google-map --host 0.0.0.0 --port 3000 --apikey "YOUR_API_KEY"

Then configure your MCP client:

{
  "mcpServers": {
    "google-maps": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Server Information

• Transport: stdio (--stdio) or Streamable HTTP (default)
• Tools: 18 Google Maps tools (14 atomic + 4 composite) — filterable via GOOGLE_MAPS_ENABLED_TOOLS

CLI Exec Mode (Agent Skill)

Use tools directly without running the MCP server:

npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'

All 18 tools available: geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation, timezone, weather, air-quality, static-map, batch-geocode-tool, search-along-route, explore-area, plan-route, compare-places, local-rank-tracker. See skills/google-maps/ for the agent skill definition and full parameter docs.

Batch Geocode

Geocode hundreds of addresses from a file:

npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -

Input: one address per line. Output: JSON with { total, succeeded, failed, results[] }. Default concurrency: 20 parallel requests.

API Key Configuration

API keys can be provided in three ways (priority order):

1. HTTP Headers (Highest priority)

   {
     "mcp-google-map": {
       "transport": "streamableHttp",
       "url": "http://localhost:3000/mcp",
       "headers": {
         "X-Google-Maps-API-Key": "YOUR_API_KEY"
       }
     }
   }
   

2. Command Line

   mcp-google-map --apikey YOUR_API_KEY
   

3. Environment Variable (.env file or command line)

   GOOGLE_MAPS_API_KEY=your_api_key_here
   MCP_SERVER_PORT=3000
   MCP_SERVER_HOST=0.0.0.0
   

Development

Local Development

# Clone the repository
git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map

# Install dependencies
npm install

# Set up environment variables
cp .env.example .env
# Edit .env with your API key

# Build the project
npm run build

# Start the server
npm start

# Or run in development mode
npm run dev

Testing

# Run smoke tests (no API key required for basic tests)
npm test

# Run full E2E tests (requires GOOGLE_MAPS_API_KEY)
npm run test:e2e

Project Structure

src/
├── cli.ts                        # CLI entry point
├── config.ts                     # Tool registration and server config
├── index.ts                      # Package exports
├── core/
│   └── BaseMcpServer.ts          # MCP server with streamable HTTP transport
├── services/
│   ├── NewPlacesService.ts       # Google Places API (New) client
│   ├── PlacesSearcher.ts         # Service facade layer
│   ├── RoutesService.ts          # Google Routes API client (directions, distance matrix, waypoint optimization)
│   └── toolclass.ts              # Google Maps API client (geocoding, timezone, elevation, static map)
├── tools/
│   └── maps/
│       ├── searchNearby.ts       # maps_search_nearby tool
│       ├── searchPlaces.ts       # maps_search_places tool
│       ├── placeDetails.ts       # maps_place_details tool
│       ├── geocode.ts            # maps_geocode tool
│       ├── reverseGeocode.ts     # maps_reverse_geocode tool
│       ├── distanceMatrix.ts     # maps_distance_matrix tool
│       ├── directions.ts         # maps_directions tool
│       ├── elevation.ts          # maps_elevation tool
│       ├── timezone.ts           # maps_timezone tool
│       ├── weather.ts