MCP Google Map Server

A powerful Model Context Protocol (MCP) server providing comprehensive Google Maps API integration with streamable HTTP transport support and LLM processing capabilities.

🙌 Special Thanks

This project has received contributions from the community.
Special thanks to @junyinnnn for helping add support for streamablehttp.

✅ Testing Status

This MCP server has been tested and verified to work correctly with:

Claude Desktop
Dive Desktop
MCP protocol implementations

All tools and features are confirmed functional through real-world testing.

Features

🆕 Latest Updates

ℹ️ Reminder: enable Places API (New) in https://console.cloud.google.com before using the new Place features.

🗺️ Google Maps Integration

Location Search
- Search for places near a specific location with customizable radius and filters
- Get detailed place information including ratings, opening hours, and contact details
Geocoding Services
- Convert addresses to coordinates (geocoding)
- Convert coordinates to addresses (reverse geocoding)
Distance & Directions
- Calculate distances and travel times between multiple origins and destinations
- Get detailed turn-by-turn directions between two points
- Support for different travel modes (driving, walking, bicycling, transit)
Elevation Data
- Retrieve elevation data for specific locations

🚀 Advanced Features

Streamable HTTP Transport: Latest MCP protocol with real-time streaming capabilities
Session Management: Stateful sessions with UUID-based identification
Multiple Connection Support: Handle multiple concurrent client connections
Echo Service: Built-in testing tool for MCP server functionality

Installation

⚠️ Important Notice: This server uses HTTP transport, not stdio. Direct npx usage in MCP Server Settings is NOT supported.

Method 1: Global Installation (Recommended)

# Install globally
npm install -g @cablate/mcp-google-map

# Run the server
mcp-google-map --port 3000 --apikey "your_api_key_here"

# Using short options
mcp-google-map -p 3000 -k "your_api_key_here"

Method 2: Using npx (Quick Start)

⚠️ Warning: Cannot be used directly in MCP Server Settings with stdio mode

Step 1: Launch HTTP Server in Terminal

# Run in a separate terminal
npx @cablate/mcp-google-map --port 3000 --apikey "YOUR_API_KEY"

# Or with environment variable
GOOGLE_MAPS_API_KEY=YOUR_API_KEY npx @cablate/mcp-google-map

Step 2: Configure MCP Client to Use HTTP

{
  "mcp-google-map": {
    "transport": "http",
    "url": "http://localhost:3000/mcp"
  }
}

❌ Common Mistake to Avoid

// This WILL NOT WORK - stdio mode not supported with npx
{
  "mcp-google-map": {
    "command": "npx",
    "args": ["@cablate/mcp-google-map"]
  }
}

Server Information

Endpoint: http://localhost:3000/mcp
Transport: HTTP (not stdio)
Tools: 8 Google Maps tools available

API Key Configuration

API keys can be provided in three ways (priority order):

HTTP Headers (Highest priority)

// MCP Client config
{
  "mcp-google-map": {
    "transport": "streamableHttp",
    "url": "http://localhost:3000/mcp",
    // if your MCP Client support 'headers'
    "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

Available Tools

The server provides the following tools:

Google Maps Tools

search_nearby - Search for nearby places based on location, with optional filtering by keywords, distance, rating, and operating hours
get_place_details - Get detailed information about a specific place including contact details, reviews, ratings, and operating hours
maps_geocode - Convert addresses or place names to geographic coordinates (latitude and longitude)
maps_reverse_geocode - Convert geographic coordinates to a human-readable address
maps_distance_matrix - Calculate travel distances and durations between multiple origins and destinations
maps_directions - Get detailed turn-by-turn navigation directions between two locations
maps_elevation - Get elevation data (height above sea level) for specific geographic locations

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

Project Structure

src/
├── cli.ts                    # Main CLI entry point
├── config.ts                 # Server configuration
├── index.ts                  # Package exports
├── core/
│   └── BaseMcpServer.ts     # Base MCP server with streamable HTTP
└── tools/
    └── maps/                # Google Maps tools
        ├── toolclass.ts     # Google Maps API client
        ├── searchPlaces.ts  # Maps service layer
        ├── searchNearby.ts  # Search nearby places
        ├── placeDetails.ts  # Place details
        ├── geocode.ts       # Geocoding
        ├── reverseGeocode.ts # Reverse geocoding
        ├── distanceMatrix.ts # Distance matrix
        ├── directions.ts    # Directions
        └── elevation.ts     # Elevation data

Tech Stack

TypeScript - Type-safe development
Node.js - Runtime environment
Google Maps Services JS - Google Maps API integration
Model Context Protocol SDK - MCP protocol implementation
Express.js - HTTP server framework
Zod - Schema validation

Security Considerations

API keys are handled server-side for security
DNS rebinding protection available for production
Input validation using Zod schemas
Error handling and logging

License

MIT

Contributing

Community participation and contributions are welcome! Here's how you can contribute:

⭐️ Star the project if you find it helpful
🐛 Submit Issues: Report bugs or provide suggestions
🔧 Create Pull Requests: Submit code improvements
📖 Documentation: Help improve documentation

Contact

If you have any questions or suggestions, feel free to reach out:

📧 Email: [email protected]
💻 GitHub: CabLate
🤝 Collaboration: Welcome to discuss project cooperation
📚 Technical Guidance: Sincere welcome for suggestions and guidance

Changelog

v0.0.19 (Latest)

New Places API Integration: Updated to use Google's new Places API (New) instead of the legacy API to resolve HTTP 403 errors and ensure continued functionality.

v0.0.18

Error response improvements: Now all error messages are in English with more detailed information (previously in Chinese)

v0.0.17

Added HTTP Header Authentication: Support for passing API keys via X-Google-Maps-API-Key header in MCP Client config
Fixed Concurrent User Issues: Each session now uses its own API key without conflicts
Fixed npx Execution: Resolved module bundling issues
Improved Documentation: Clearer setup instructions

v0.0.14

Added streamable HTTP transport support
Improved CLI interface with emoji indicators
Enhanced error handling and logging
Added comprehensive tool descriptions for LLM integration
Updated to latest MCP SDK version

谷歌地图