README.md•8.64 kB
# 🗺️ MCP Google Maps Server
[](https://www.npmjs.com/package/@vicente-alvarado/mcp-google-map-stdio)
[](https://opensource.org/licenses/MIT)
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í](#obtener-api-key-de-google-maps))
## 🚀 Instalación
### Opción 1: Instalación Global (Recomendado)
```bash
npm install -g @vicente-alvarado/mcp-google-map-stdio
```
### Opción 2: Desde el Repositorio
```bash
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
```bash
mcp-google-map-stdio --version
```
## 🔑 Obtener API Key de Google Maps
1. Ve a [Google Cloud Console](https://console.cloud.google.com/)
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](./CLAUDE_DESKTOP.md)**
### Para Otros Clientes MCP
Si quieres integrar este servidor con tu propio cliente MCP:
📖 **[Guía de Uso con Clientes MCP](./MCP_USAGE.md)**
## 🛠️ 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)
```bash
# 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)
```bash
# 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
```bash
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
```typescript
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](LICENSE) para más detalles.
## 🙏 Agradecimientos
- [Anthropic](https://www.anthropic.com/) por Claude y el protocolo MCP
- [Google Maps Platform](https://developers.google.com/maps) por las APIs
- La comunidad de código abierto
## 📞 Soporte
- 🐛 [Reportar un bug](https://github.com/vicente-alvarado/mcp-google-map-stdio/issues)
- 💡 [Solicitar una feature](https://github.com/vicente-alvarado/mcp-google-map-stdio/issues)
- 📧 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**