Mcp Google Map Server

What is Mcp Google Map Server about?

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.

How to use Mcp Google Map Server?

STDIO mode (ideal for Claude Desktop, Cursor, VS Code, or any MCP client that supports stdio):
```
npx @cablate/mcp-google-map --stdio
```

Exec CLI mode (run a single tool without a persistent server):

npx @cablate/mcp-google-map exec geocode '{"address":"Tokyo Tower"}'
npx @cablate/mcp-google-map exec search-places '{"query":"ramen in Tokyo"}'

HTTP server mode (multi‑session, remote access, per‑request API‑key isolation):

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"
    }
  }
}

API‑key provision – supplied via HTTP header X-Google-Maps-API-Key, command‑line --apikey, or environment variable GOOGLE_MAPS_API_KEY (priority shown in README).

Key Features

Eight fully‑featured tools: geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation.
Three transport modes: stdio, Streamable HTTP (default), and standalone exec CLI.
Built‑in Agent Skill located under skills/google-maps/ that teaches LLMs how to chain the tools.
Open‑source MIT license and self‑hostable, enabling private deployments and per‑tenant API‑key isolation.
Type‑safe TypeScript codebase with Zod schema validation for all inputs.
Security features: server‑side key handling, DNS rebinding protection, and strict request validation.

Use Cases

Location‑aware assistants – enable chat agents to answer "Where is the nearest sushi restaurant?" or provide step‑by‑step navigation.
Geospatial data enrichment – augment datasets with coordinates, elevation, or place metadata.
Route optimization – calculate travel times and distances for logistics or delivery applications.
Travel planning bots – generate itineraries with directions, place details, and elevation profiles for hiking routes.
Enterprise multi‑tenant AI services – host a private MCP server to serve different internal teams with isolated API keys.

FAQ

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.

8 tools — geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation
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	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

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

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"
      }
    }
  }
}

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"

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: 8 Google Maps 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 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 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

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
│   └── 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

Tech Stack

TypeScript - Type-safe development
Node.js - Runtime environment
@googlemaps/places - Google Places API (New) for place search and details
@googlemaps/google-maps-services-js - Legacy API for geocoding, directions, distance matrix, 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.

Changelog

See CHANGELOG.md for version history.

License

MIT

Contributing

Community participation and contributions are welcome!

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

Contact

Email: reahtuoo310109@gmail.com
GitHub: CabLate

Mcp Google Map Server