Google Maps MCP Server
cablate/mcp-google-map
The Mcp Google Map server provides AI agents with geospatial capabilities through 18 tools covering geocoding, place search, routing, elevation, distance matrix, timezone, weather, air quality, and map imagery, along with four composite tools for complex tasks like trip planning and location comparison. It operates in multiple modes (stdio, HTTP, and CLI) and includes built-in agent skill definitions to help AI models chain geographic operations together. The server solves the problem of giving language models practical understanding of the physical world by integrating Google Maps APIs in a structured, tool-based format that agents can reason about and utilize autonomously.
- GitHub stars
- 338
- tools
- 8
- last updated
- Apr 21, 2026
Tools
8 toolsPublic tool metadata for what this MCP can expose to an agent.
GOOGLE_MAPS_COMPUTE_ROUTE_MATRIXCalculates travel distance and duration matrix between multiple origins and destinations using the modern Routes API; supports OAuth2 authentication and various travel modes.7 params
Calculates travel distance and duration matrix between multiple origins and destinations using the modern Routes API; supports OAuth2 authentication and various travel modes.
Parameters* required
destinationsarrayList of destination locations. Each can be specified as an address or latitude/longitude coordinates.
fieldMaskstringComma-separated list of response fields to include (e.g., 'originIndex,destinationIndex,duration,distanceMeters'). Use '*' for all fields.default: originIndex,destinationIndex,duration,distanceMeters,status,condition
languageCodestringBCP-47 language code (e.g., 'en-US', 'es') for textual information.default: en-US
originsarrayList of origin locations. Each can be specified as an address or latitude/longitude coordinates.
routingPreferencestringSpecifies routing preference: `TRAFFIC_UNAWARE` (fastest, ignores traffic), `TRAFFIC_AWARE` (considers traffic, optimized), `TRAFFIC_AWARE_OPTIMAL` (most accurate traffic-based routing), or `ROUTIN...one of
ROUTING_PREFERENCE_UNSPECIFIED · TRAFFIC_UNAWARE · TRAFFIC_AWARE · TRAFFIC_AWARE_OPTIMALdefault: TRAFFIC_AWAREtravelModestringMode of transportation for the route matrix calculation.one of
DRIVE · BICYCLE · WALK · TWO_WHEELER · TRANSITdefault: DRIVEunitsstringUnit system (e.g., 'METRIC' for kilometers, 'IMPERIAL' for miles) for displaying distances.one of
METRIC · IMPERIALdefault: IMPERIALGOOGLE_MAPS_DISTANCE_MATRIX_APIDEPRECATED: Legacy API that calculates travel distance and time for a matrix of origins and destinations. This API only works with API keys (no OAuth2 support). Use the modern 'Compute Route Matrix' action instead, which supports OAuth2 authentication. Supports different modes...13 params
DEPRECATED: Legacy API that calculates travel distance and time for a matrix of origins and destinations. This API only works with API keys (no OAuth2 support). Use the modern 'Compute Route Matrix' action instead, which supports OAuth2 authentication. Supports different modes...
Parameters* required
arrival_timeintegerSpecifies the desired time of arrival for transit directions, in seconds since midnight, January 1, 1970 UTC. You can specify either departure_time or arrival_time, but not both.
avoidstringIndicates that the calculated route should avoid the specified features. Multiple values can be pipe-separated e.g. 'tolls|highways'.one of
tolls · highways · ferries · indoordeparture_timeintegerSpecifies the desired time of departure. You can specify the time as an integer in seconds since midnight, January 1, 1970 UTC, or as the string 'now'. Required for duration_in_traffic.
destinationsstringOne or more locations to use as the finishing point for calculating travel distance and time. Accepts the same formats as origins.
keystringYour application's API key. This key identifies your application for purposes of quota management.
languagestringThe language in which to return results. See the list of supported languages: https://developers.google.com/maps/faq#languagesupport
modestringSpecifies the mode of transport to use.one of
driving · walking · bicycling · transitdefault: drivingoriginsstringThe starting point for calculating travel distance and time. You can supply one or more locations separated by the pipe character (|), in the form of a place ID (prefixed with place_id:), an addres...
regionstringThe region code, specified as a ccTLD ('top-level domain') two-character value. This helps influence results based on the region.
traffic_modelstringSpecifies the assumptions to use when calculating time in traffic. This parameter is only used if the request includes a departure_time and mode is 'driving'.one of
best_guess · pessimistic · optimistictransit_modestringSpecifies one or more preferred modes of transit. This parameter may only be specified for transit directions. Multiple values can be pipe-separated e.g. 'bus|train'.one of
bus · subway · train · tram · railtransit_routing_preferencestringSpecifies preferences for transit routes. This parameter may only be specified for transit directions.one of
less_walking · fewer_transfersunitsstringSpecifies the unit system to use when displaying results. The default is metric.one of
metric · imperialGOOGLE_MAPS_GEOCODING_APIDEPRECATED: Legacy API to convert addresses into geographic coordinates (latitude and longitude) and vice versa (reverse geocoding), or get an address for a Place ID. This API only works with API keys (no OAuth2 support). Consider using the modern Places API (Text Search or Ne...11 params
DEPRECATED: Legacy API to convert addresses into geographic coordinates (latitude and longitude) and vice versa (reverse geocoding), or get an address for a Place ID. This API only works with API keys (no OAuth2 support). Consider using the modern Places API (Text Search or Ne...
Parameters* required
addressstringThe street address or plus code that you want to geocode. Provide for geocoding (address to coordinates).
boundsstringThe bounding box of the viewport within which to bias geocode results more prominently (e.g., '34.172684,-118.604794|34.236144,-118.500938'). This parameter will only influence, not fully restrict,...
componentsstringA components filter with elements separated by a pipe (|). E.g., 'postal_code:94043|country:US'. Used for geocoding, can be restrictive or biasing.
extra_computationsarrayUse this parameter to specify additional features in the response. Can select multiple values.
keystringYour application's API key. If not provided, will be extracted from connection metadata.
languagestringThe language in which to return results. If language is not supplied, the geocoder attempts to use the preferred language as specified in the Accept-Language header, or the native language of the d...
latlngstringThe latitude and longitude coordinates specifying the location for which you want the closest, human-readable address (e.g., '40.714224,-73.961452'). Provide for reverse geocoding.
location_typestringA filter of one or more location types, separated by a pipe (|) (e.g., 'ROOFTOP|RANGE_INTERPOLATED'). Used for reverse geocoding and place ID geocoding.
place_idstringThe place ID of the place for which you wish to obtain the human-readable address. Provide for place ID geocoding.
regionstringThe region code, specified as a ccTLD ('top-level domain') two-character value. This parameter will only influence, not fully restrict, results from the geocoder.
result_typestringA filter of one or more address types, separated by a pipe (|) (e.g., 'street_address|locality'). Used for reverse geocoding and place ID geocoding.
GOOGLE_MAPS_GET_DIRECTIONDEPRECATED: Legacy API that fetches detailed directions between an origin and a destination, supporting intermediate waypoints and various travel modes. This API only works with API keys (no OAuth2 support). Use the modern 'Get Route' action instead, which supports OAuth2 auth...7 params
DEPRECATED: Legacy API that fetches detailed directions between an origin and a destination, supporting intermediate waypoints and various travel modes. This API only works with API keys (no OAuth2 support). Use the modern 'Get Route' action instead, which supports OAuth2 auth...
Parameters* required
avoidstringSpecifies features to avoid in the generated route. Multiple values can be combined using a pipe delimiter (e.g., 'tolls|highways'). Valid options include 'tolls', 'highways', and 'ferries'.
destinationstringThe ending point for the directions. This can be a textual address (e.g., '456 Park Ave, New York, NY'), a place name (e.g., 'Universal Studios Hollywood'), or latitude/longitude coordinates (e.g.,...
languagestringThe language code for returning results, e.g., 'en' for English, 'es' for Spanish. Defaults to 'en'.default: en
modestringThe mode of transportation for which to calculate directions. Supported values are 'driving' (default), 'walking', 'bicycling', and 'transit'.default: driving
originstringThe starting point for the directions. This can be a textual address (e.g., '123 Main St, Los Angeles, CA'), a place name (e.g., 'Disneyland'), or latitude/longitude coordinates (e.g., '34.0522,-11...
unitsstringThe unit system for displaying distances. Supported values are 'metric' (kilometers and meters) and 'imperial' (miles and feet). Defaults to 'imperial'.default: imperial
waypointsstringA comma-separated string of intermediate locations (addresses, place names, or coordinates) to visit between the origin and destination.
GOOGLE_MAPS_GET_ROUTECalculates one or more routes between two specified locations. Uses various travel modes and preferences; addresses must be resolvable by Google Maps.11 params
Calculates one or more routes between two specified locations. Uses various travel modes and preferences; addresses must be resolvable by Google Maps.
Parameters* required
computeAlternativeRoutesbooleanComputes and returns alternative routes if true.default: false
destination_addressstringDestination point address or place name for the route calculation.
fieldMaskstringComma-separated list of `Route` object fields to include in the response (e.g., 'routes.distanceMeters,routes.duration') for efficiency.default: routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline
languageCodestringBCP-47 language code (e.g., 'en-US', 'es') for textual information like navigation instructions.default: en-US
origin_addressstringStarting point address or place name for the route calculation.
routeModifiers_avoidFerriesbooleanAttempts to avoid ferries if true.default: false
routeModifiers_avoidHighwaysbooleanAttempts to avoid highways if true.default: false
routeModifiers_avoidTollsbooleanAttempts to avoid toll roads if true.default: false
routingPreferencestringSpecifies routing preference: `TRAFFIC_UNAWARE` (fastest, ignores traffic), `TRAFFIC_AWARE` (considers traffic, optimized), `TRAFFIC_AWARE_OPTIMAL` (most accurate traffic-based routing), or `ROUTIN...one of
ROUTING_PREFERENCE_UNSPECIFIED · TRAFFIC_UNAWARE · TRAFFIC_AWARE · TRAFFIC_AWARE_OPTIMALtravelModestringMode of transportation for the route.one of
DRIVE · BICYCLE · WALK · TWO_WHEELER · TRANSITdefault: DRIVEunitsstringUnit system (e.g., 'METRIC' for kilometers, 'IMPERIAL' for miles) for displaying distances.one of
METRIC · IMPERIALdefault: IMPERIALGOOGLE_MAPS_MAPS_EMBED_APITool to generate an embeddable Google Map URL and HTML iframe code. Use when you need to display a map (place, view, directions, street view, search) on a webpage without JavaScript. Note: This API only works with API keys (no OAuth2 support). It generates embed URLs and does...6 params
Tool to generate an embeddable Google Map URL and HTML iframe code. Use when you need to display a map (place, view, directions, street view, search) on a webpage without JavaScript. Note: This API only works with API keys (no OAuth2 support). It generates embed URLs and does...
Parameters* required
directions_paramsobjectParameters for 'directions' mode.
modestringThe mode of the embedded map.one of
place · view · directions · streetview · searchplace_paramsobjectParameters for 'place' mode.
search_paramsobjectParameters for 'search' mode.
streetview_paramsobjectParameters for 'streetview' mode.
view_paramsobjectParameters for 'view' mode.
GOOGLE_MAPS_NEARBY_SEARCHSearches for places (e.g., restaurants, parks) within a specified circular area, with options to filter by place types and customize the returned fields and number of results.7 params
Searches for places (e.g., restaurants, parks) within a specified circular area, with options to filter by place types and customize the returned fields and number of results.
Parameters* required
excludedTypesarrayPlace types to exclude (e.g., 'cafe', 'store'); results matching any of these types are omitted. For supported types, see Google Maps Places API documentation.
fieldMaskstringComma-separated list of place fields for the response (e.g., 'places.displayName,places.formattedAddress'); use '*' for all fields.default: places.displayName
includedTypesarrayPlace types to include (e.g., 'restaurant', 'park'); results will match at least one of these types. For supported types, see Google Maps Places API documentation.
latitudenumberLatitude coordinate of the search center in decimal degrees.
longitudenumberLongitude coordinate of the search center in decimal degrees.
maxResultCountintegerMaximum number of search results to return (up to 20); the actual count may be lower.default: 10
radiusnumberRadius of the circular search area in meters.
GOOGLE_MAPS_TEXT_SEARCHSearches for places on Google Maps using a textual query (e.g., "restaurants in London", "Eiffel Tower").3 params
Searches for places on Google Maps using a textual query (e.g., "restaurants in London", "Eiffel Tower").
Parameters* required
fieldMaskstringComma-separated list of place fields to return. Use `*` for all fields (not recommended for performance/cost). See Google Maps Places API documentation for field names.default: places.displayName,places.formattedAddress,places.priceLevel
maxResultCountintegerMaximum number of place results to return (must be 1-20). Note: Google prefers `pageSize`, but this action uses `maxResultCount`.default: 10
textQuerystringText query for searching places. Matched against place name, address, and category.
Sponsors
Configuration
GOOGLE_MAPS_API_KEY*secretGoogle Maps API key (get one at https://console.cloud.google.com)
GOOGLE_MAPS_ENABLED_TOOLSComma-separated tool names to enable. Omit or * for all 18 tools.
Readme
Google Maps for AI agents
Stop rebuilding place search, routing, and location workflows for every AI app.
@cablate/mcp-google-map turns Google Maps Platform into 18 read-only agent tools and three focused Skills. An agent can find real places, verify routes, compare options, build practical itineraries, or audit local search visibility—through MCP or a standalone CLI.
You choose the integration model: Codex or Claude Code Plugin when you want Skills without MCP setup, stdio for desktop MCP clients, or Streamable HTTP for shared and remote deployments.
English · 繁體中文
Why use it?
Giving an agent a raw Maps API is only the beginning. Useful answers often require several dependent calls: resolve a place, preserve its identity, search around it, check opening details, calculate travel time, and explain what was actually verified. This project packages that work into one consistent interface.
- Move from lookup to outcome. Atomic tools handle geocoding, place details, directions, weather, air quality, and maps. Composite tools explore areas, compare candidates, optimize stops, and measure local rankings.
- Use the same capabilities with or without MCP. The standalone
execCLI works with Agent Skills and automation; the MCP server exposes the same 18 tools over stdio or HTTP. - Give agents workflow guidance, not just function names. Three Skills cover general map research, evidence-backed travel planning, and local SEO. Codex loads their full instructions only when a request matches.
- Keep deployment and credentials under your control. Run locally or self-host. API keys remain in your environment or request headers, with per-session isolation for HTTP deployments.
- Start narrow and grow later. Register only the tools you need with
GOOGLE_MAPS_ENABLED_TOOLS, or use the full catalog.
What can an agent do?
| Outcome | How the project helps |
|---|---|
| Find and evaluate real places | Natural-language and nearby search, place details, ratings, hours, reviews, and distance comparison |
| Build a trip that works geographically | Candidate discovery, along-route stops, travel-time checks, multi-stop optimization, weather, and static maps |
| Research a neighborhood | Multi-category exploration plus targeted distance, elevation, timezone, weather, and air-quality checks |
| Plan field work or deliveries | Route matrices and optimized stop ordering for up to 25 stops |
| Audit local search visibility | Geographic grid ranking, competitor discovery, ARP, ATRP, and SoLV metrics |
| Enrich location data | Single or batch geocoding, reverse geocoding, and structured JSON output |
These are data and planning tools, not guarantees of safety, accessibility, opening status, or ranking outcomes. Applications displaying Places reviews, photos, or AI summaries must follow the content attribution and storage guidance.
Choose your integration
| Use | Best for | What runs |
|---|---|---|
| Codex Plugin | Asking Codex map, travel, or local SEO questions without MCP configuration | A matching Skill loads on demand and calls the standalone CLI |
| Claude Code Plugin | Installing the same three Skills from a Claude marketplace | Skills are namespaced under mcp-google-map and call the standalone CLI |
| Standalone CLI | Scripts, automation, and other Skill-compatible agents | One stateless command returns JSON |
| MCP stdio | Claude Desktop, Cursor, VS Code, and other local MCP clients | The client starts a local MCP process |
| Streamable HTTP | Multi-session, containerized, LAN, or remote access | A self-hosted server exposes /mcp |
All options require Node.js 22+ and a Google Maps Platform API key. Live calls may be billable. Enable the APIs needed by your selected tools; common place and route workflows require Places API (New), Routes API, and often Geocoding API.
Start with Codex—no MCP required
codex plugin marketplace add cablate/mcp-google-map --ref main
codex plugin add mcp-google-map@cablate
Set GOOGLE_MAPS_API_KEY in the environment where Codex runs, then start a new conversation. Verify the local setup without making a Google API request:
npx -y @cablate/mcp-google-map doctor
Success means the node, package, and api-key checks pass and live-api is skipped. Use doctor --live only when you intend to send potentially billable checks to Geocoding, Places, and Routes.
Try asking:
Plan a practical two-day Kyoto itinerary. Group nearby places, check travel times, and explain any opening-hour assumptions.
Codex selects google-maps for general location research, google-maps-travel-planning for itineraries, or google-maps-local-seo for business visibility analysis. The plugin does not register or start an MCP server. See the no-MCP walkthrough for a reproducible example.
Install in Claude Code—no MCP required
claude plugin marketplace add cablate/mcp-google-map
claude plugin install mcp-google-map@cablate-maps
Start a new Claude Code session, set GOOGLE_MAPS_API_KEY in its environment, and run the same doctor check shown above. Claude exposes the installed Skills with the plugin namespace, for example /mcp-google-map:google-maps-travel-planning.
Each GitHub release also includes a versioned mcp-google-map-claude-plugin-v*.zip and SHA-256 checksum for direct distribution. The release workflow builds this archive from the same skills/ source and validates it with Claude Code's official strict validator before publishing.
Use the standalone CLI
Every MCP tool also has a short CLI name:
npx -y @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx -y @cablate/mcp-google-map exec search-places '{"query":"quiet cafes in Kyoto"}'
npx -y @cablate/mcp-google-map exec directions '{"origin":"Tokyo Station","destination":"Tokyo Skytree","mode":"transit"}'
Each call is stateless. Successful calls return { "success": true, "data": ... } on stdout; failures exit nonzero and write structured JSON to stderr.
For bulk address enrichment:
npx @cablate/mcp-google-map batch-geocode -i addresses.txt -o results.json
cat addresses.txt | npx @cablate/mcp-google-map batch-geocode -i -
Connect an MCP client
stdio
{
"mcpServers": {
"google-maps": {
"command": "npx",
"args": ["-y", "@cablate/mcp-google-map", "--stdio"],
"env": { "GOOGLE_MAPS_API_KEY": "YOUR_API_KEY" }
}
}
}
To reduce tool-list context, add a comma-separated allowlist such as "GOOGLE_MAPS_ENABLED_TOOLS": "maps_geocode,maps_directions,maps_search_places". Omit it or use * to expose all tools.
Streamable HTTP
npx @cablate/mcp-google-map --host 127.0.0.1 --port 3000 --apikey "YOUR_API_KEY"
{
"mcpServers": {
"google-maps": {
"type": "http",
"url": "http://127.0.0.1:3000/mcp"
}
}
}
Bind to 0.0.0.0 only when the server must accept external connections. For multi-tenant deployments, prefer the X-Google-Maps-API-Key request header so keys remain isolated by session.
Tool catalog
| Group | Tools |
|---|---|
| Places and discovery | maps_search_places, maps_search_nearby, maps_place_details, maps_explore_area, maps_compare_places, maps_search_along_route |
| Location and routing | maps_geocode, maps_reverse_geocode, maps_directions, maps_distance_matrix, maps_plan_route, maps_batch_geocode |
| Context and visualization | maps_elevation, maps_timezone, maps_weather, maps_air_quality, maps_static_map |
| Local SEO | maps_local_rank_tracker |
All 18 tools declare readOnlyHint: true and destructiveHint: false. Exact parameters, response shapes, and workflow recipes live in the tool reference.
API key and Google Cloud setup
The key must belong to a Google Cloud project with billing enabled and restrictions compatible with the runtime. The setup and diagnostics guide maps each capability to its required API and explains common failures.
Credential priority is:
X-Google-Maps-API-KeyHTTP request header--apikeycommand-line optionGOOGLE_MAPS_API_KEYenvironment variable
Prefer environment variables or request headers. Command-line secrets can appear in shell history and process listings.
Trust and limits
- Place and route facts come from the Google Maps Platform APIs enabled for your project; weather availability has regional limitations.
- A successful API response does not prove accessibility, safety, legal suitability, or real-time availability.
- The package preserves source and disclosure metadata where returned, but your interface remains responsible for compliant attribution and storage.
- HTTP mode supports per-session API-key isolation and DNS rebinding protection.
- This project is MIT licensed and self-hostable. See SECURITY.md for vulnerability reporting and Security Assessment Clarifications for the review checklist.
Development
git clone https://github.com/cablate/mcp-google-map.git
cd mcp-google-map
npm ci
npm run build
npm run test:unit
npm test
Live E2E calls require GOOGLE_MAPS_API_KEY and may be billable: npm run test:e2e.
Contributions are welcome. Read CONTRIBUTING.md before opening a pull request. Release history is in CHANGELOG.md.
Acknowledgements
Thanks to @junyinnnn for helping add Streamable HTTP support.
License
Details
- Repository
- github.com/cablate/mcp-google-map
- Category
- Search & Web Crawling
- Package
@cablate/mcp-google-map- Transport
- STDIO
- Auth
- Required
- Registry
- MCP registry, active
