PluginBench
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.

RepositoryRegistry
How to choose

What this kind of tool is for

  • Scaffold, lint, or restyle a component your agent is already editing.
  • Run accessibility, link, or screenshot checks against a local build.
  • Turn a design constraint into generated markup the agent can iterate on.

How to compare servers like this

Framework fit:
Check the tool targets your stack (React, Vue, plain HTML) before installing it.
Runtime needs:
Some browser-driving tools need a local browser or display; read the setup notes first.
Maintenance signal:
Frontend tooling churns quickly; recent commits are a good filter.
Output quality:
Prefer tools whose generated code you would accept into the repo as-is.

This page carries your copy-paste config: pick your MCP client in the install section on this page and use the copy button.

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 calculation, weather, air quality, elevation, timezone, and route optimization. It supports stdio and HTTP transports and includes built-in agent skills for travel planning, real estate analysis, and local SEO workflows.

This server gives AI agents the ability to understand and reason about the physical world by providing access to Google Maps APIs. You can geocode addresses, search for nearby places, get step-by-step directions, calculate distances, check weather and air quality, retrieve elevation data, and plan optimized multi-stop routes. It's useful for travel planning, logistics optimization, real estate analysis, field sales routing, and local SEO auditing.

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.

~/Library/Application Support/Claude/claude_desktop_config.json
JSON config
{
  "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>"
      }
    }
  }
}

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.
  • 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.

Use cases

  • Plan multi-day travel itineraries with geocoding, place search, directions, weather, and route optimization
  • Analyze neighborhoods for real estate: schools, commute times, flood risk (elevation), and amenities nearby
  • Optimize delivery or field sales routes across multiple stops with waypoint optimization
  • Audit local SEO performance: track business ranking vs competitors within a geographic radius
  • Disaster response: find nearest open hospitals, check elevation for flood zones, and get air quality data

Google Maps MCP Server MCP server FAQ

What is the Google Maps MCP Server?

It's an MCP server that exposes 18 Google Maps tools to AI agents, including geocoding, place search, directions, distance matrix, weather, air quality, elevation, timezone, and route optimization. It supports both stdio and HTTP transports.

Is it free to use?

The server itself is open-source (MIT license), but it requires a Google Cloud API key and uses Google Maps APIs, which have usage-based 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: set the command to 'npx @cablate/mcp-google-map --stdio' and provide your GOOGLE_MAPS_API_KEY as an environment variable.

What authentication is required?

You need a Google Cloud API key with Places API (New) and Routes API enabled. The key can be provided via environment variable (GOOGLE_MAPS_API_KEY), command-line argument, or HTTP header (X-Google-Maps-API-Key).

Can I reduce context usage by disabling some tools?

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') to register only the tools you need.

Does it support multi-language responses?

Language parameter support is planned but not yet implemented. Currently, responses are in the default language for the region queried.

README (reference)

Source of truth, from the repository.

<p align="center"> <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> </p> <p align="center"> <img src="./assets/banner.webp" alt="MCP Google Maps — AI-Powered Geospatial Tools" width="800"> </p> <h3 align="center"><b>Give your AI agent the ability to understand the physical world —<br>geocode, route, search, and reason about locations.</b></h3> <p align="center"> <b>English</b> | <a href="./README.zh-TW.md">繁體中文</a> </p> <p align="center"> <img src="./assets/demo-grid-en.png" alt="Travel planning demo — Kyoto 2-day, Tokyo outdoor, Japan 5-day, Bangkok budget" width="800"> </p>
  • 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 projectGrounding Lite
Tools183
GeocodingYesNo
Step-by-step directionsYesNo
ElevationYesNo
Distance matrixYesNo
Place detailsYesNo
TimezoneYesNo
WeatherYesYes
Air qualityYesNo
Map imagesYesNo
Composite tools (explore, plan, compare)YesNo
Open sourceMITNo
Self-hostedYesGoogle-managed only
Agent SkillYesNo

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

ToolDescription
maps_search_nearbyFind places near a location by type (restaurant, cafe, hotel, etc.). Supports filtering by radius, rating, and open status.
maps_search_placesFree-text place search (e.g., "sushi restaurants in Tokyo"). Supports location bias, rating, open-now filters.
maps_place_detailsGet full details for a place by its place_id — reviews, phone, website, hours. Optional maxPhotos param returns photo URLs.
maps_geocodeConvert an address or landmark name into GPS coordinates.
maps_reverse_geocodeConvert GPS coordinates into a street address.
maps_distance_matrixCalculate travel distances and times between multiple origins and destinations.
maps_directionsGet step-by-step navigation between two points with route details.
maps_elevationGet elevation (meters above sea level) for geographic coordinates.
maps_timezoneGet timezone ID, name, UTC/DST offsets, and local time for coordinates.
maps_weatherGet current weather conditions or forecast — temperature, humidity, wind, UV, precipitation.
maps_air_qualityGet air quality index, pollutant concentrations, and health recommendations by demographic group.
maps_static_mapGenerate a map image with markers, paths, or routes — returned inline for the user to see directly.
maps_batch_geocodeGeocode up to 50 addresses in one call — returns coordinates for each.
maps_search_along_routeSearch for places along a route between two points — ranked by minimal detour time.
Composite Tools
maps_explore_areaExplore what's around a location — searches multiple place types and gets details in one call.
maps_plan_routePlan an optimized multi-stop route — uses Routes API waypoint optimization (up to 25 stops) for efficient ordering.
maps_compare_placesCompare places side-by-side — searches, gets details, and optionally calculates distances.
maps_local_rank_trackerTrack 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       # 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 / FeatureWhat it unlocksStatus
maps_static_mapMap images with pins/routes — multimodal AI can "see" the mapDone
maps_air_qualityAQI, pollutants — health-aware travel, outdoor planningDone
maps_batch_geocodeGeocode up to 50 addresses in one call — data enrichmentDone
maps_search_along_routeFind places along a route ranked by detour time — trip planningDone
maps_explore_areaOne-call neighborhood overview (composite)Done
maps_plan_routeOptimized multi-stop itinerary (composite)Done
maps_compare_placesSide-by-side place comparison (composite)Done
maps_local_rank_trackerGeographic grid rank tracking — local SEO analysis (composite)Done
GOOGLE_MAPS_ENABLED_TOOLSFilter tools to reduce context usageDone

Planned

FeatureWhat it unlocksStatus
maps_place_photoPlace photos for multimodal AI — "see" the restaurant ambiancePlanned
Language parameterMulti-language responses (ISO 639-1) across all toolsPlanned
MCP Prompt Templates/travel-planner, /neighborhood-scout slash commands in Claude DesktopPlanned
Geo-Reasoning Benchmark10-scenario test suite measuring LLM geospatial reasoning accuracyResearch

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

Star History

<a href="https://glama.ai/mcp/servers/@cablate/mcp-google-map"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@cablate/mcp-google-map/badge" alt="Google Map Server MCP server" /> </a>

Star History Chart

Related MCP servers

CUCustom AI View logo

Custom AI View

Maintained

See any site as it looks on a real iPhone, iPad or MacBook — and drive that window over MCP.

1
JavaScript
View repository →

MCP server for loading authenticated web pages using Chrome DevTools Protocol

7
JavaScript
MIT
View repository →

Tock (exploretock.com): discover restaurants, search a city, get venue details and availability.

0
TypeScript
MIT
View repository →

Upload, organize, search, and transform images, videos, and files with AI-powered tools.

0
TypeScript
MIT
View repository →

Persistent memory + causal root-cause analysis for AI coding agents. 124 MCP tools. EU, GDPR.

2
TypeScript
Apache-2.0
View repository →

Model Context Protocol server that wraps the CADLens REST API.

0
TypeScript
MIT
View repository →