MCP Google Map README

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

Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget

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

bash

# 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. Driving mode supports `avoid_tolls` and `avoid_highways`.
`maps_directions`	Get step-by-step navigation between two points with route details. Driving mode supports `avoid_tolls` and `avoid_highways`.
`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. Driving mode supports `avoid_tolls` and `avoid_highways`.
`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:

config.json

{
  "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:

config.json

{
  "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:

Terminal

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:

config.json

{
  "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:

Terminal

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:

Terminal

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

HTTP Headers (Highest priority)

config.json

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

Command Line
bash
```
mcp-google-map --apikey YOUR_API_KEY
```

Environment Variable (.env file or command line)

env

GOOGLE_MAPS_API_KEY=your_api_key_here
MCP_SERVER_PORT=3000
MCP_SERVER_HOST=0.0.0.0

Development

Local Development

bash

# 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

bash

# 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

Code

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       # maps_batch_geocode tool
│       ├── searchAlongRoute.ts   # maps_search_along_route tool
│       ├── exploreArea.ts        # maps_explore_area (composite)
│       ├── planRoute.ts          # maps_plan_route (composite)
│       ├── comparePlaces.ts      # maps_compare_places (composite)
│       └── localRankTracker.ts   # maps_local_rank_tracker (composite)
└── utils/
    ├── apiKeyManager.ts          # API key management
    └── requestContext.ts         # Per-request context (API key isolation)
tests/
└── smoke.test.ts                 # Smoke + E2E test suite
skills/
├── google-maps/                  # Agent Skill — how to USE the tools
│   ├── SKILL.md                  # Tool map, recipes, invocation
│   └── references/
│       ├── tools-api.md          # Tool parameters + scenario recipes
│       ├── travel-planning.md    # Travel planning methodology
│       └── local-seo.md          # Local SEO / Google Business Profile ranking analysis
└── project-docs/                 # Project Skill — how to DEVELOP/MAINTAIN
    ├── SKILL.md                  # Architecture overview + onboarding
    └── references/
        ├── architecture.md       # System design, code map, 9-file checklist
        ├── google-maps-api-guide.md  # API endpoints, pricing, gotchas
        ├── geo-domain-knowledge.md   # GIS fundamentals, Japan context
        └── decisions.md          # 10 ADRs (design decisions + rationale)

Tech Stack

TypeScript - Type-safe development
Node.js - Runtime environment
@googlemaps/places - Google Places API (New) for place search and details
Google Routes API - Directions, distance matrix, and waypoint optimization via REST
@googlemaps/google-maps-services-js - Geocoding, timezone, elevation
@modelcontextprotocol/sdk - MCP protocol implementation (v1.27+)
Express.js - HTTP server framework
Zod - Schema validation

Security

API keys are handled server-side
Per-session API key isolation for multi-tenant deployments
DNS rebinding protection available for production
Input validation using Zod schemas

For enterprise security reviews, see Security Assessment Clarifications — a 23-item checklist covering licensing, data protection, credential management, tool contamination, and AI agent execution environment verification.

To report a vulnerability, see SECURITY.md.

Roadmap

Recent Additions

Tool / Feature	What it unlocks	Status
`maps_static_map`	Map images with pins/routes — multimodal AI can "see" the map	Done
`maps_air_quality`	AQI, pollutants — health-aware travel, outdoor planning	Done
`maps_batch_geocode`	Geocode up to 50 addresses in one call — data enrichment	Done
`maps_search_along_route`	Find places along a route ranked by detour time — trip planning	Done
`maps_explore_area`	One-call neighborhood overview (composite)	Done
`maps_plan_route`	Optimized multi-stop itinerary (composite)	Done
`maps_compare_places`	Side-by-side place comparison (composite)	Done
`maps_local_rank_tracker`	Geographic grid rank tracking — local SEO analysis (composite)	Done
`GOOGLE_MAPS_ENABLED_TOOLS`	Filter tools to reduce context usage	Done

Planned

Feature	What it unlocks	Status
`maps_place_photo`	Place photos for multimodal AI — "see" the restaurant ambiance	Planned
Language parameter	Multi-language responses (ISO 639-1) across all tools	Planned
MCP Prompt Templates	`/travel-planner`, `/neighborhood-scout` slash commands in Claude Desktop	Planned
Geo-Reasoning Benchmark	10-scenario test suite measuring LLM geospatial reasoning accuracy	Research

Use Cases We're Building Toward

These are the real-world scenarios driving our tool decisions:

Travel planning — "Plan a day trip in Tokyo" (geocode → search → directions → weather)
Real estate analysis — "Analyze this neighborhood: schools, commute, flood risk" (search-nearby × N + elevation + distance-matrix)
Logistics optimization — "Route these 12 deliveries efficiently from the warehouse" (plan-route)
Field sales — "Visit 6 clients in Chicago, minimize drive time, find lunch spots" (plan-route + search-nearby)
Disaster response — "Nearest open hospitals? Am I in a flood zone?" (search-nearby + elevation)
Content creation — "Top 5 neighborhoods in Austin with restaurant density and airport distance" (explore-area + distance-matrix)
Accessibility — "Wheelchair-accessible restaurants, avoid steep routes" (search-nearby + place-details + elevation)
Local SEO — "Audit my restaurant's ranking vs competitors within 1km" (search-places + compare-places + explore-area)

Changelog

See CHANGELOG.md for version history.

License

MIT

Contributing

Community participation and contributions are welcome! Please read CONTRIBUTING.md for development setup, coding guidelines, and the pull request process.

Submit Issues: Report bugs or provide suggestions
Create Pull Requests: Submit code improvements
Documentation: Help improve documentation

Contact

Email: reahtuoo310109@gmail.com
GitHub: CabLate

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

vs Google Grounding Lite

Quick Start

Special Thanks

Available Tools

Installation

Method 1: stdio (Recommended for most clients)

Method 2: HTTP Server

Server Information

CLI Exec Mode (Agent Skill)

Batch Geocode

API Key Configuration

Development

Local Development

Testing

Project Structure

Tech Stack

Security

Roadmap

Recent Additions

Planned

Use Cases We're Building Toward

Changelog

License

Contributing

Contact

Star History

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