MCP Server

Maintained

MIT

Google Maps MCP Server MCP Server

io.github.cablate/google-map

18 Google Maps tools for AI agents — geocode, search, directions, weather, elevation, and more.

What is the Google Maps MCP Server MCP server?

The Google Maps MCP Server is an MCP server that exposes 18 Google Maps tools (14 atomic + 4 composite) to AI agents, enabling geocoding, place search, directions, distance calculations, weather, air quality, and route optimization. It supports stdio, HTTP, and CLI modes, with built-in agent skill definitions for chaining geo tools.

This server gives Claude, Cursor, and other AI agents access to comprehensive geospatial capabilities powered by Google Maps APIs. Use it for travel planning, real estate analysis, logistics optimization, local SEO audits, and any task requiring location intelligence — from finding nearby restaurants to planning multi-stop routes and tracking business rankings across geographic grids.

How to install Google Maps MCP Server

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

GOOGLE_MAPS_API_KEY
required
secret
Google Maps API key (get one at https://console.cloud.google.com)
GOOGLE_MAPS_ENABLED_TOOLS
Comma-separated tool names to enable. Omit or * for all 18 tools.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "google-map": {
      "command": "npx",
      "args": [
        "-y",
        "@cablate/mcp-google-map"
      ],
      "env": {
        "GOOGLE_MAPS_API_KEY": "<YOUR_GOOGLE_MAPS_API_KEY>",
        "GOOGLE_MAPS_ENABLED_TOOLS": "<YOUR_GOOGLE_MAPS_ENABLED_TOOLS>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "google-map": {
      "command": "npx",
      "args": [
        "-y",
        "@cablate/mcp-google-map"
      ],
      "env": {
        "GOOGLE_MAPS_API_KEY": "<YOUR_GOOGLE_MAPS_API_KEY>",
        "GOOGLE_MAPS_ENABLED_TOOLS": "<YOUR_GOOGLE_MAPS_ENABLED_TOOLS>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "google-map": {
      "command": "npx",
      "args": [
        "-y",
        "@cablate/mcp-google-map"
      ],
      "env": {
        "GOOGLE_MAPS_API_KEY": "<YOUR_GOOGLE_MAPS_API_KEY>",
        "GOOGLE_MAPS_ENABLED_TOOLS": "<YOUR_GOOGLE_MAPS_ENABLED_TOOLS>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "google-map": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@cablate/mcp-google-map"
      ],
      "env": {
        "GOOGLE_MAPS_API_KEY": "<YOUR_GOOGLE_MAPS_API_KEY>",
        "GOOGLE_MAPS_ENABLED_TOOLS": "<YOUR_GOOGLE_MAPS_ENABLED_TOOLS>"
      }
    }
  }
}

Claude Code

claude mcp add google-map --env GOOGLE_MAPS_API_KEY=<YOUR_GOOGLE_MAPS_API_KEY> --env GOOGLE_MAPS_ENABLED_TOOLS=<YOUR_GOOGLE_MAPS_ENABLED_TOOLS> -- npx -y @cablate/mcp-google-map

Tools & capabilities

Tools this server exposes to the agent.

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.
maps_explore_area — Explore what's around a location — searches multiple place types and gets details in one call (composite).
maps_plan_route — Plan an optimized multi-stop route — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering (composite).
maps_compare_places — Compare places side-by-side — searches, gets details, and optionally calculates distances (composite).
maps_local_rank_tracker — Track a business's local search ranking across a geographic grid — supports up to 3 keywords for batch scanning, returns rank at each point, top-3 competitors, and metrics (composite).

Use cases

Plan multi-day trips with geocoding, place search, directions, weather, and elevation data
Optimize delivery routes and field sales visits with waypoint optimization for up to 25 stops
Analyze neighborhoods for real estate by searching nearby amenities, schools, and calculating commute distances
Audit local SEO rankings and compare business visibility vs competitors across geographic grids
Find accessible routes and facilities by combining place search, elevation, and place details

Google Maps MCP Server MCP server FAQ

What is the Google Maps MCP Server?

It's an MCP server with 18 Google Maps tools (geocoding, place search, directions, weather, air quality, elevation, timezone, and more) that enables AI agents to understand and reason about the physical world. It includes 14 atomic tools and 4 composite tools for complex tasks like route planning and local SEO tracking.

Is it free to use?

The server itself is open-source (MIT license) and free. However, it requires a Google Cloud API key and uses Google Maps APIs, which are subject to Google Cloud pricing. You must enable Places API (New) and Routes API in Google Cloud Console.

How do I install it in Claude Desktop or Cursor?

Add it to your MCP configuration as a stdio server: use `npx @cablate/mcp-google-map --stdio` as the command and set `GOOGLE_MAPS_API_KEY` as an environment variable. Alternatively, run it as an HTTP server on localhost and configure the client to connect via HTTP.

What authentication is required?

You need a Google Cloud API key with Places API (New) and Routes API enabled. Provide it via environment variable (GOOGLE_MAPS_API_KEY), command-line flag (--apikey), or HTTP header (X-Google-Maps-API-Key).

Can I limit which tools are available to reduce context usage?

Yes. Set the `GOOGLE_MAPS_ENABLED_TOOLS` environment variable to a comma-separated list of tool names (e.g., 'maps_geocode,maps_directions,maps_search_places'). Omit or set to '*' for all 18 tools.

Does it support multi-session or remote deployments?

Yes. Run it as an HTTP server with `npx @cablate/mcp-google-map --port 3000 --apikey YOUR_KEY` and bind to 0.0.0.0 for remote access. It supports per-request API key isolation via HTTP headers.

README (reference)

Source of truth, from the repository.

<a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/v/@cablate/mcp-google-map" alt="npm version"></a> <a href="https://www.npmjs.com/package/@cablate/mcp-google-map"><img src="https://img.shields.io/npm/dm/@cablate/mcp-google-map" alt="npm downloads"></a> <a href="https://github.com/cablate/mcp-google-map/stargazers"><img src="https://img.shields.io/github/stars/cablate/mcp-google-map?style=social" alt="GitHub stars"></a> <a href="./LICENSE"><img src="https://img.shields.io/github/license/cablate/mcp-google-map" alt="license"></a> <img src="./assets/banner.webp" alt="MCP Google Maps — AI-Powered Geospatial Tools" width="800"> <h3 align="center">Give your AI agent the ability to understand the physical world — geocode, route, search, and reason about locations.</h3> English | <a href="./README.zh-TW.md">繁體中文</a> <img src="./assets/demo-grid-en.png" alt="Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget" width="800">

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

HTTP Headers (Highest priority)

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

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

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       # 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

Star History

View repository →