🗺️ MCP Google Maps Server

Un servidor MCP (Model Context Protocol) para Google Maps que proporciona acceso a servicios de mapas, geocodificación, búsqueda de lugares y navegación.

✨ Características

• 🔌 STDIO Nativo: Comunicación directa sin proxies ni wrappers
• 🌐 Modo HTTP: También soporta HTTP para desarrollo y testing
• 🗺️ APIs Completas: Places, Geocoding, Directions, Distance Matrix y Elevation
• 🚀 Alto Rendimiento: Comunicación optimizada y sin latencias adicionales
• 🛡️ Robusto: Manejo de errores y validación de parámetros
• 📦 Fácil de instalar: Instalación via npm

📋 Requisitos

• Node.js >= 18.0.0
• API Key de Google Maps (obtener aquí)

🚀 Instalación

Opción 1: Instalación Global (Recomendado)

npm install -g @vicente-alvarado/mcp-google-map-stdio

Opción 2: Desde el Repositorio

git clone https://github.com/vicente-alvarado/mcp-google-map-stdio.git
cd mcp-google-map-stdio
npm install
npm run build
npm install -g .

Verificar Instalación

mcp-google-map-stdio --version

🔑 Obtener API Key de Google Maps

1. Ve a Google Cloud Console
2. Crea un proyecto nuevo o selecciona uno existente
3. Habilita las siguientes APIs:
   • Places API (New)
   • Geocoding API
   • Directions API
   • Distance Matrix API
   • Elevation API
4. Ve a "Credenciales" y crea una API Key
5. (Recomendado) Restringe la API key solo a las APIs habilitadas

⚠️ Importante: Nunca expongas tu API key en código fuente público. Usa variables de entorno.

🎯 Uso

Este servidor soporta dos modos de operación:

Para Claude Desktop

Si quieres usar este servidor con Claude Desktop, consulta la guía específica:

📖 Guía de Configuración para Claude Desktop

Para Otros Clientes MCP

Si quieres integrar este servidor con tu propio cliente MCP:

📖 Guía de Uso con Clientes MCP

🛠️ Herramientas Disponibles

search_nearby

Busca lugares cercanos a una ubicación específica.

Parámetros:

• center: Ubicación central (dirección o coordenadas)
• radius: Radio de búsqueda en metros (default: 1000)
• keyword: Palabra clave para filtrar (opcional)
• minRating: Calificación mínima (opcional)
• openNow: Solo lugares abiertos ahora (opcional)

Ejemplo: Buscar restaurantes cerca de Times Square

---

get_place_details

Obtiene información detallada de un lugar específico.

Parámetros:

• placeId: ID del lugar de Google Maps

Ejemplo: Obtener detalles del Empire State Building

---

maps_geocode

Convierte direcciones en coordenadas geográficas.

Parámetros:

• address: Dirección a geocodificar

Ejemplo: Obtener coordenadas de "Torre Eiffel, París"

---

maps_reverse_geocode

Convierte coordenadas en direcciones legibles.

Parámetros:

• latitude: Latitud
• longitude: Longitud

Ejemplo: Obtener dirección de (40.7128, -74.0060)

---

maps_distance_matrix

Calcula distancias y tiempos entre múltiples puntos.

Parámetros:

• origins: Lista de puntos de origen
• destinations: Lista de puntos de destino
• mode: Modo de viaje (driving, walking, bicycling, transit)

Ejemplo: Calcular tiempo de Manhattan a Brooklyn

---

maps_directions

Obtiene direcciones detalladas entre dos puntos.

Parámetros:

• origin: Punto de partida
• destination: Punto de llegada
• mode: Modo de viaje (driving, walking, bicycling, transit)
• departure_time: Hora de salida (opcional)
• arrival_time: Hora de llegada (opcional)

Ejemplo: Direcciones del JFK a Times Square

---

maps_elevation

Obtiene información de elevación de ubicaciones.

Parámetros:

• locations: Lista de ubicaciones (coordenadas)

Ejemplo: Obtener elevación del Monte Everest

🧪 Testing

Test Rápido (STDIO)

# Ejecutar el servidor en modo STDIO
GOOGLE_MAPS_API_KEY="tu_api_key" mcp-google-map-stdio --stdio

# O usar el script de test incluido
node test-stdio.js

Test en Modo HTTP (Desarrollo)

# Iniciar servidor HTTP
GOOGLE_MAPS_API_KEY="tu_api_key" MCP_SERVER_PORT=3000 mcp-google-map-stdio

# Probar con curl
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "X-Google-Maps-API-Key: tu_api_key" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'

🏗️ Arquitectura

Modo STDIO (Para MCP Clients como Claude Desktop)

MCP Client (Claude Desktop)
    ↓ stdin (JSON-RPC messages)
    ↓
BaseMcpServer (StdioServerTransport)
    ↓ Google Maps APIs
    ↓ stdout (JSON-RPC responses)
    ↓
MCP Client

Modo HTTP (Para Desarrollo/Testing)

HTTP Client
    ↓ HTTP POST
    ↓
BaseMcpServer (HTTP :3000)
    ↓ Google Maps APIs
    ↓ HTTP Response
    ↓
HTTP Client

🔧 Desarrollo

Estructura del Proyecto

mcp-google-map-stdio/
├── src/
│   ├── cli.ts                 # CLI principal
│   ├── index.ts               # Exports
│   ├── config.ts              # Configuración
│   ├── core/
│   │   └── BaseMcpServer.ts   # Servidor MCP base
│   ├── services/
│   │   ├── PlacesSearcher.ts  # Servicio de búsqueda
│   │   └── toolclass.ts       # Clase base herramientas
│   ├── tools/
│   │   └── maps/              # Implementación herramientas
│   └── utils/
│       ├── apiKeyManager.ts   # Gestión API keys
│       └── requestContext.ts  # Contexto requests
├── dist/                      # Build output
└── test-stdio.js              # Script de test

Scripts Disponibles

npm run build        # Construir el proyecto
npm start            # Iniciar en modo HTTP
npm run start:stdio  # Iniciar en modo STDIO
npm run dev          # Desarrollo con watch mode

Crear Tu Propia Herramienta

import { z } from "zod";

export const MiHerramienta = {
  NAME: "mi_herramienta",
  DESCRIPTION: "Descripción de mi herramienta",
  SCHEMA: {
    param1: z.string().describe("Descripción parámetro 1"),
    param2: z.number().optional().describe("Descripción parámetro 2")
  },
  ACTION: async (params: any) => {
    // Lógica de tu herramienta
    return {
      content: [{
        type: "text",
        text: JSON.stringify(resultado)
      }],
      isError: false
    };
  }
};

🤝 Contribuir

Las contribuciones son bienvenidas! Por favor:

1. Fork el proyecto
2. Crea una rama para tu feature (git checkout -b feature/NuevaCaracteristica)
3. Commit tus cambios (git commit -m 'Add: Nueva característica')
4. Push a la rama (git push origin feature/NuevaCaracteristica)
5. Abre un Pull Request

📝 Changelog

v1.0.1 (2025-01-08)

• ✅ Implementación nativa de STDIO con StdioServerTransport
• ✅ Eliminado wrapper HTTP innecesario
• ✅ Logs correctos (stderr para logs, stdout para JSON-RPC)
• ✅ Mejor rendimiento (~80-180ms más rápido)
• ✅ Arquitectura simplificada
• ✅ Documentación reorganizada

v1.0.0 (2025-01-07)

• 🎉 Release inicial
• ✅ Soporte HTTP básico
• ✅ 7 herramientas de Google Maps

📄 Licencia

Este proyecto está bajo la licencia MIT - ver el archivo LICENSE para más detalles.

🙏 Agradecimientos

• Anthropic por Claude y el protocolo MCP
• Google Maps Platform por las APIs
• La comunidad de código abierto

📞 Soporte

• 🐛 Reportar un bug
• 💡 Solicitar una feature
• 📧 Email: contacto@example.com

⚠️ Importante

• API Key: Nunca compartas tu API key públicamente
• Costos: Las APIs de Google Maps pueden tener costos asociados
• Límites: Revisa los límites de uso en Google Cloud Console
• Seguridad: Restringe tu API key solo a las APIs necesarias

---

Hecho con ❤️ para la comunidad MCP