cablate/mcp-google-map
If you are the rightful owner of mcp-google-map and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
A powerful Model Context Protocol (MCP) server providing comprehensive Google Maps API integration with LLM processing capabilities.
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
๐บ๏ธ 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
1. via NPM
npm install -g @cablate/mcp-google-map
2. 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"
# Show help information
mcp-google-map --help
3. Server Endpoints
- Main MCP Endpoint:
http://localhost:3000/mcp
- Available Tools: 8 tools including Google Maps services and echo
Environment Variables
Alternatively, create a .env
file in your working directory:
# Required
GOOGLE_MAPS_API_KEY=your_google_maps_api_key_here
# Optional
MCP_SERVER_PORT=3000
Note: Command line options take precedence over environment variables.
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/
โโโ echo.ts # Echo service tool
โโโ 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: reahtuoo310109@gmail.com
- ๐ป GitHub: CabLate
- ๐ค Collaboration: Welcome to discuss project cooperation
- ๐ Technical Guidance: Sincere welcome for suggestions and guidance
Changelog
v0.0.5
- 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
v0.0.4
- Initial release with basic Google Maps integration
- Support for location search, geocoding, and directions
- Compatible with MCP protocol