cablate/mcp-google-map

Give your AI agent the ability to understand the physical world —
geocode, route, search, and reason about locations.

English | 繁體中文

• 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