Give your AI agent the ability to understand the physical world — geocode, route, search, and reason about locations.

• 13 tools — 10 atomic + 3 composite (explore-area, plan-route, compare-places)
• 3 modes — stdio, StreamableHTTP, standalone exec CLI
• Agent Skill — built-in skill definition teaches AI how to chain geo tools (skills/google-maps/)

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

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

• Transport: stdio (--stdio) or Streamable HTTP (default)
• Tools: 13 Google Maps tools (10 atomic + 3 composite)

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 13 tools available: geocode, reverse-geocode, search-nearby, search-places, place-details, directions, distance-matrix, elevation, timezone, weather, explore-area, plan-route, compare-places. See skills/google-maps/ for the agent skill definition and full parameter docs.

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

# 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       # 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
│       ├── exploreArea.ts        # maps_explore_area (composite)
│       ├── planRoute.ts          # maps_plan_route (composite)
│       └── comparePlaces.ts      # maps_compare_places (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/
    ├── SKILL.md                  # Agent skill definition
    └── references/
        └── tools-api.md          # Tool parameter reference

• 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

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

See CHANGELOG.md for version history.

MIT

Community participation and contributions are welcome!

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

• Email: reahtuoo310109@gmail.com
• GitHub: CabLate