Google Maps MCP Server

A Model Context Protocol (MCP) server that integrates Google Maps routing and traffic capabilities with Claude AI for advanced route planning, traffic analysis, and cost estimation.

Prerequisites

Node.js (LTS version 18+ recommended) - Download from nodejs.org
Google Maps API Key with required services enabled
Claude Desktop application for MCP integration

Setup Instructions

1. Clone and Install

git clone [your-repo-url]
cd google-maps-mcp-server
npm install

2. Get Google Maps API Key

Go to Google Cloud Console
Create a new project or select existing one
Enable the following APIs:
- Directions API (required for routing)
- Distance Matrix API (required for traffic data)
- Geocoding API (required for address lookup)
- Places API (optional, for enhanced address search)
Create credentials → API Key
Restrict the API key to the enabled services above

3. Configure API Key

Edit config/config.json and replace GOOGLE_API_KEY with your actual API key:

{
  "googleMaps": {
    "apiKey": "your-actual-api-key-here"
  }
}

4. Test the Server

# Test configuration
npm test

# Start in development mode
npm run dev

5. Configure Claude Desktop

Add this to your Claude Desktop MCP settings file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-maps": {
      "command": "node",
      "args": ["/absolute/path/to/google-maps-mcp-server/src/index.js"],
      "cwd": "/absolute/path/to/google-maps-mcp-server"
    }
  }
}

6. Start Using

Restart Claude Desktop and you can now ask questions like:

"Find the fastest route from New York to Boston"
"Compare routes to the airport with and without tolls"
"What's the traffic like for my commute right now?"

Available Tools

calculate_route: Get optimal route with traffic consideration and waypoints
compare_routes: Compare multiple route alternatives with different options
get_live_traffic: Get real-time traffic information and travel delays
estimate_costs: Calculate trip costs including fuel and toll estimates

Troubleshooting

Common Issues

1. "Please set your Google Maps API key" error

Check that config/config.json has your actual API key, not GOOGLE_API_KEY
Ensure the JSON format is valid (no trailing commas)

2. "Google Maps API error" messages

Verify your API key is valid and has the required APIs enabled
Check API quotas and billing in Google Cloud Console
Ensure your API key isn't restricted to wrong domains/IPs

3. "No route found" errors

Check that addresses are valid and exist
Try using coordinates instead of addresses (lat,lng format)
Verify the locations are accessible by car

4. Server won't start

# Check Node.js version
node --version  # Should be 18+

# Clear dependencies and reinstall
rm -rf node_modules package-lock.json
npm install

# Check for configuration errors
npm test

5. Claude Desktop can't find the server

Use absolute paths in Claude Desktop config
Restart Claude Desktop after configuration changes
Check that the MCP config file path is correct for your OS

Debug Mode

Run with debug logging:

DEBUG=* npm start

Testing Individual Tools

# Test route calculation
echo '{"origin":"New York, NY","destination":"Boston, MA"}' | node src/index.js

# Check API connectivity
curl "https://maps.googleapis.com/maps/api/directions/json?origin=NYC&destination=Boston&key=YOUR_API_KEY"

Configuration Options

Edit config/config.json to customize:

{
  "googleMaps": {
    "apiKey": "your-api-key"
  },
  "server": {
    "port": 3001,
    "host": "localhost"
  },
  "routing": {
    "defaultTrafficModel": "best_guess",
    "maxWaypoints": 25,
    "maxAlternatives": 3,
    "units": "metric"
  },
  "costs": {
    "fuelPricePerLiter": 1.50,
    "vehicleFuelEfficiency": 8.0,
    "tollEstimatePerKm": 0.05
  }
}

License

MIT License - feel free to modify and distribute.