by cablate
Provides AI agents with full Google Maps capabilities—geocoding, reverse‑geocoding, nearby searches, place details, directions, distance matrices, and elevation—via the Model Context Protocol.
Mcp Google Map Server equips AI agents with eight Google Maps tools that allow them to interpret, query, and reason about real‑world locations. The server implements the Model Context Protocol so agents can invoke geospatial operations directly from their prompts.
npx @cablate/mcp-google-map --stdio
npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'
npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
Then configure the MCP client:
{
"mcpServers": {
"google-maps": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
X-Google-Maps-API-Key, command‑line --apikey, or environment variable GOOGLE_MAPS_API_KEY (priority shown in README).geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation.skills/google-maps/ that teaches LLMs how to chain the tools.Q: Do I need a Google Cloud project? A: Yes. Enable the Places API (New) and obtain a Google Maps API key.
Q: Can I run the server without internet access? A: The tools call Google Maps services, so an internet connection is required.
Q: Which transport should I choose? A: Use stdio for single‑user desktop integrations, HTTP for multi‑session or remote deployments, and exec CLI for quick ad‑hoc calls.
Q: How are API keys protected? A: Keys are never exposed to the client; they are read from environment variables or request headers and used only on the server side.
Q: Is the server compatible with other MCP clients? A: Yes. Any client that implements the Model Context Protocol can consume the tools via stdio or Streamable HTTP.
Give your AI agent the ability to understand the physical world — geocode, route, search, and reason about locations.
skills/google-maps/)| This project | Grounding Lite | |
|---|---|---|
| Tools | 8 | 3 |
| Geocoding | Yes | No |
| Step-by-step directions | Yes | No |
| Elevation | Yes | No |
| Distance matrix | Yes | No |
| Place details | Yes | No |
| Open source | MIT | No |
| Self-hosted | Yes | Google-managed only |
| Agent Skill | Yes | No |
# 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 to @junyinnnn for helping add support for streamablehttp.
| Tool | Description |
|---|---|
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. |
get_place_details |
Get full details for a place by its place_id — reviews, phone, website, hours, photos. |
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. |
All tools are annotated with readOnlyHint: true and destructiveHint: false — MCP clients can auto-approve these without user confirmation.
Prerequisite: Enable Places API (New) in Google Cloud Console before using place-related tools.
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"
}
}
}
}
For multi-session deployments, per-request API key isolation, or remote access:
npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"
Then configure your MCP client:
{
"mcpServers": {
"google-maps": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}
--stdio) or Streamable HTTP (default)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 8 tools available: geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation. See skills/google-maps/ for the agent skill definition and full parameter docs.
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
# 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
# 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
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
│ └── toolclass.ts # Legacy Google Maps API client
├── tools/
│ └── maps/
│ ├── searchNearby.ts # search_nearby tool
│ ├── searchPlaces.ts # maps_search_places tool
│ ├── placeDetails.ts # get_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
└── 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/
├── SKILL.md # Agent skill definition
└── references/
└── tools-api.md # Tool parameter reference
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.
See CHANGELOG.md for version history.
MIT
Community participation and contributions are welcome!
Please log in to share your review and rating for this MCP.
Explore related MCPs that share similar capabilities and solve comparable challenges
by modelcontextprotocol
An MCP server implementation that provides a tool for dynamic and reflective problem-solving through a structured thinking process.
by danny-avila
Provides a self‑hosted ChatGPT‑style interface supporting numerous AI models, agents, code interpreter, image generation, multimodal interactions, and secure multi‑user authentication.
by block
Automates engineering tasks on local machines, executing code, building projects, debugging, orchestrating workflows, and interacting with external APIs using any LLM.
by RooCodeInc
Provides an autonomous AI coding partner inside the editor that can understand natural language, manipulate files, run commands, browse the web, and be customized via modes and instructions.
by pydantic
A Python framework that enables seamless integration of Pydantic validation with large language models, providing type‑safe agent construction, dependency injection, and structured output handling.
by mcp-use
A Python SDK that simplifies interaction with MCP servers and enables developers to create custom agents with tool‑calling capabilities.
by lastmile-ai
Build effective agents using Model Context Protocol and simple, composable workflow patterns.
by Klavis-AI
Provides production‑ready MCP servers and a hosted service for integrating AI applications with over 50 third‑party services via standardized APIs, OAuth, and easy Docker or hosted deployment.
by nanbingxyz
A cross‑platform desktop AI assistant that connects to major LLM providers, supports a local knowledge base, and enables tool integration via MCP servers.
{
"mcpServers": {
"google-maps": {
"command": "npx",
"args": [
"-y",
"@cablate/mcp-google-map",
"--stdio"
],
"env": {
"GOOGLE_MAPS_API_KEY": "YOUR_API_KEY"
}
}
}
}claude mcp add google-maps npx -y @cablate/mcp-google-map --stdio