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

| | This project | Grounding Lite | |---|---|---| | Tools | 18 | 3 | | Geocoding | Yes | No | | Step-by-step directions | Yes | No | | Elevation | Yes | No | | Distance matrix | Yes | No | | Place details | Yes | No | | Timezone | Yes | No | | Weather | Yes | Yes | | Air quality | Yes | No | | Map images | Yes | No | | Composite tools (explore, plan, compare) | Yes | No | | Open source | MIT | No | | Self-hosted | Yes | Google-managed only | | Agent Skill | Yes | No |

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

| Tool | Description | |------|-------------| | maps_search_nearby | Find places near a location by type (restaurant, cafe, hotel, etc.). Supports filtering by radius, rating, and open status. | | maps_search_places | Free-text place search (e.g., "sushi restaurants in Tokyo"). Supports location bias, rating, open-now filters. | | maps_place_details | Get full details for a place by its place_id — reviews, phone, website, hours. Optional maxPhotos param returns photo URLs. | | maps_geocode | Convert an address or landmark name into GPS coordinates. | | maps_reverse_geocode | Convert GPS coordinates into a street address. | | maps_distance_matrix | Calculate travel distances and times between multiple origins and destinations. | | maps_directions | Get step-by-step navigation between two points with route details. | | maps_elevation | Get elevation (meters above sea level) for geographic coordinates. | | maps_timezone | Get timezone ID, name, UTC/DST offsets, and local time for coordinates. | | maps_weather | Get current weather conditions or forecast — temperature, humidity, wind, UV, precipitation. | | maps_air_quality | Get air quality index, pollutant concentrations, and health recommendations by demographic group. | | maps_static_map | Generate a map image with markers, paths, or routes — returned inline for the user to see directly. | | maps_batch_geocode | Geocode up to 50 addresses in one call — returns coordinates for each. | | maps_search_along_route | Search for places along a route between two points — ranked by minimal detour time. | | Composite Tools | | | maps_explore_area | Explore what's around a location — searches multiple place types and gets details in one call. | | maps_plan_route | Plan an optimized multi-stop route — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering. | | maps_compare_places | Compare places side-by-side — searches, gets details, and optionally calculates distances. | | maps_local_rank_tracker | Track a business's local search ranking across a geographic grid — like LocalFalcon. Supports up to 3 keywords for batch scanning. Returns rank at each point, top-3 competitors, and metrics (ARP, ATRP, SoLV). |

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            # maps_weather tool
│       ├── airQuality.ts         # maps_air_quality tool
│       ├── staticMap.ts          # maps_static_map tool
│       ├── batchGeocode.ts