google-maps-comprehensive-mcp

Google Maps MCP Server

MCP Server per le API moderne di Google Maps (Places API, Routes API, Geocoding API, Elevation API). Supporta geocoding, ricerca luoghi, dettagli di posti, calcolo di distanze, elevazioni e percorsi.

Tools Disponibili

🗺️ 8 Tools Implementati

1. maps_ping (Health Check)

• Verifica se il server MCP è attivo
• Input: nessuno
• Output: "Google Maps MCP server is alive ✅"

1. maps_geocode

• Converte un indirizzo in coordinate geografiche
• Input: address (string)
• Output: location, formatted_address, place_id, address_components

1. maps_reverse_geocode

• Converte coordinate in un indirizzo leggibile
• Input:
• latitude (number)
• longitude (number)
• Output: formatted_address, place_id, address_components

1. maps_search_places

• Ricerca luoghi tramite query testuale usando Places API (New)
• Input: query (string)
• Output: array di luoghi con displayName, formattedAddress, location, types

1. maps_place_details

• Ottieni informazioni dettagliate su un luogo
• Input: place_id (string)
• Output: name, address, contact info, ratings, reviews, opening hours, photos

1. maps_distance_matrix

• Calcola distanze e tempi tra multiple origini e destinazioni
• Input:
• origins (string[])
• destinations (string[])
• mode (optional): "driving" | "walking" | "bicycling" | "transit"
• Output: matrice di distances e durations

1. maps_elevation

• Recupera dati di elevazione per punti geografici
• Input: locations (array di { latitude, longitude })
• Output: elevation e resolution per ogni punto

1. maps_directions

• Ottieni indicazioni stradali tra due punti usando Routes API (New)
• Input:
• origin (string)
• destination (string)
• travelMode (optional): "DRIVE" | "WALK" | "BICYCLE" | "TRANSIT"
• Output: route steps, distance, duration, polyline

---

🚀 Setup e Installazione

1. Ottenere una API Key

Crea una API key Google Maps abilitando:

• Places API (New)
• Routes API (New)
• Geocoding API
• Elevation API

Segui la guida ufficiale: Get an API Key

2. Installazione Dipendenze

npm install

3. Build del Progetto

npm run build

4. Variabile d'Ambiente

export GOOGLE_MAPS_API_KEY="your_api_key_here"

---

🔧 Uso

Esecuzione Locale

# Con variabile d'ambiente
GOOGLE_MAPS_API_KEY="your_key" node dist/index.js

# O con export
export GOOGLE_MAPS_API_KEY="your_key"
node dist/index.js

Docker

# Build dell'immagine
docker build -t google-maps-mcp .

# Esecuzione con docker-compose
GOOGLE_MAPS_API_KEY="your_key" docker-compose up

# Esecuzione diretta
docker run --rm -it -e GOOGLE_MAPS_API_KEY="your_key" google-maps-mcp

---

🎯 Configurazione MCP Client

Claude Desktop

{
  "mcpServers": {
    "google-maps": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/google-maps-mcp",
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_api_key"
      }
    }
  }
}

LM Studio

{
  "mcpServers": {
    "google-maps": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/Users/pallotta/mcp-servers/google-maps",
      "env": {
        "GOOGLE_MAPS_API_KEY": "your_api_key"
      }
    }
  }
}

Docker (Claude Desktop)

{
  "mcpServers": {
    "google-maps": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GOOGLE_MAPS_API_KEY=your_api_key",
        "google-maps-mcp"
      ]
    }
  }
}

---

🧪 Test

Il server è stato testato con successo e tutti i tool funzionano correttamente:

• ✅ maps_ping - Health check
• ✅ maps_geocode - Address → Coordinates
• ✅ maps_reverse_geocode - Coordinates → Address
• ✅ maps_search_places - Place search
• ✅ maps_place_details - Detailed place info
• ✅ maps_distance_matrix - Distance/time matrix
• ✅ maps_elevation - Elevation data
• ✅ maps_directions - Route directions

---

📋 API Utilizzate

• Google Places API (New) - Per ricerca luoghi e dettagli
• Google Routes API (New) - Per indicazioni stradali
• Google Geocoding API - Per conversione indirizzi ↔ coordinate
• Google Elevation API - Per dati di elevazione

---

🔒 Sicurezza

⚠️ Importante: Non committare mai la tua API key nel repository. Usa sempre variabili d'ambiente.

---

📝 Note

• Il server utilizza stdio transport per la comunicazione MCP
• Supporta CommonJS per compatibilità
• Tutti i tool restituiscono dati in formato JSON
• Gestione errori completa per tutte le API calls

---

🆘 Troubleshooting

Errore: "GOOGLE_MAPS_API_KEY environment variable is required"

• Assicurati di aver impostato la variabile d'ambiente
• Verifica che l'API key sia valida e abilitata

Errore: "Tool not found"

• Verifica che il server sia stato buildato correttamente: npm run build
• Controlla che tutti i tool siano implementati nel codice

Problemi Docker

• Se il container non ha i tool aggiornati, esegui: docker build --no-cache -t google-maps-mcp .
• Verifica che la variabile d'ambiente sia passata correttamente al container