Servidor MCP de GrabMaps

Un servidor de Protocolo de Contexto de Modelo (MCP) para la integración de la API de GrabMaps, que proporciona acceso a los servicios de GrabMaps a través de AWS Location Service.

Tenga en cuenta que este servidor MCP NO está afiliado oficialmente a Grab, GrabMaps ni a AWS Location Service.

Importante: GrabMaps solo admite ocho países en el sudeste asiático.

• 🇲🇾 Malasia (MYS)

• 🇸🇬 Singapur (SGP)

• 🇹🇭 Tailandia (THA)

• 🇲🇲 Myanmar (MMR)

• 🇰🇭 Camboya (KHM)

• 🇻🇳 Vietnam (VNM)

• 🇵🇭 Filipinas (PHL)

• 🇮🇩 Indonesia (IDN)

Las solicitudes de búsqueda fuera de estos países no devolverán resultados precisos.

Características

Este servidor MCP proporciona acceso a la funcionalidad de GrabMaps a través de dos categorías principales:

Acciones de Lugares (Disponibles a través de MCP)

• SearchPlaceIndexForText: Geocodificación directa para encontrar lugares por nombre o dirección

• SearchPlaceIndexForPosition: Geocodificación inversa para encontrar lugares por coordenadas

• SearchPlaceIndexForSuggestions: Obtener sugerencias de lugares mientras escribe

• GetPlace: Recuperar información detallada sobre un lugar específico

Acciones de Rutas (Disponibles a través de MCP)

• CalculateRoute: Calcular rutas entre puntos con puntos de referencia

• CalculateRouteMatrix: Calcular una matriz de rutas entre múltiples orígenes y destinos

Analítica y Monitoreo

• Firebase Analytics: Almacenamiento de analíticas basado en la nube con Firebase Realtime Database

• Copia de seguridad local: Copia de seguridad automática de archivos locales como respaldo

• Panel visual: Panel de analíticas en tiempo real con Chart.js

• Seguimiento de solicitudes: Seguimiento de solicitudes por método, punto final, IP del cliente y agente de usuario

• Seguimiento de llamadas a herramientas: Monitorear el uso y rendimiento de las herramientas MCP

Funcionalidad de Mapas (Requiere consola de AWS)

Nota: La funcionalidad de renderizado de mapas no está disponible directamente a través del servidor MCP. Para ver y usar mapas:

1. Vaya a la consola de AWS Location Service

2. Busque la sección Mapas y haga clic en el botón "Probar"

3. Asegúrese de que "Grab" esté seleccionado como proveedor

Para explorar la cobertura de datos de GrabMaps y ver los mapas en acción sin iniciar sesión en AWS, visite: https://grabmaps.grab.com/explore-data-coverage

Related MCP server: Google Maps MCP Server

Instalación

Desde NPM

npm install mcp-grabmaps

Desde el código fuente

git clone https://github.com/hithereiamaliff/mcp-grabmaps.git
cd mcp-grabmaps
npm install

Configuración

VPS / Servidor HTTP (Modo de servicio de claves)

El servidor HTTP autentica a los usuarios a través del Servicio de claves MCP. Los usuarios registran sus credenciales de GrabMaps + AWS con el servicio de claves y reciben una única clave API usr_XXXXXXXX.

Cree un archivo .env:

# MCP Key Service (required for hosted HTTP server)
KEY_SERVICE_URL=http://mcp-key-service:8090/internal/resolve
KEY_SERVICE_TOKEN=your_server_token_here

# Place Index name (default for GrabMaps)
PLACE_INDEX_NAME=explore.place.Grab

# Map name (for rendering maps)
MAP_NAME=explore.map.Grab

# Route calculator name
ROUTE_CALCULATOR_NAME=explore.route-calculator.Grab

# Server port
PORT=3000

Smithery / Desarrollo local

Cuando se ejecuta a través de Smithery o desarrollo local, las credenciales de GrabMaps y AWS se proporcionan directamente a través del esquema de configuración del SDK de Smithery (no a través del servicio de claves). Establézcalas en .env:

GRABMAPS_API_KEY=your_grabmaps_api_key_here
AWS_ACCESS_KEY_ID=your_aws_access_key_id_here
AWS_SECRET_ACCESS_KEY=your_aws_secret_access_key_here
AWS_REGION=ap-southeast-5

Uso

Método 1: Ejecución local

# Development mode
npm run dev

# Production mode
npm run build
npm start

Método 2: Uso con Smithery

# Run in development mode
npm run smithery:dev

# Build for production
npm run smithery:build

# Deploy to Smithery
npm run smithery:deploy

Pruebas en el entorno de pruebas (Playground) de Smithery

Para obtener la mejor experiencia probando las API de Lugares y Rutas, recomendamos usar el entorno de pruebas de Smithery:

1. Inicie su servidor MCP localmente: npm run dev

2. Abra el entorno de pruebas de Smithery en: https://smithery.ai/playground

3. Conéctese a su servidor MCP local: http://localhost:3000

4. Pruebe las llamadas a la API de Lugares y Rutas utilizando los ejemplos proporcionados en SMITHERY_TESTING.md

Método 3: Despliegue en VPS autohospedado

Despliegue el servidor MCP en su propio VPS con Docker y Nginx. La autenticación es manejada por el Servicio de claves MCP: los usuarios proporcionan una única clave API usr_XXXXXXXX en lugar de credenciales sin procesar.

Formato de URL de VPS

# Query parameter
https://mcp.techmavie.digital/grabmaps/mcp?api_key=usr_XXXXXXXX

# Path-based
https://mcp.techmavie.digital/grabmaps/mcp/usr_XXXXXXXX

Configuración del cliente

Claude Desktop:

{
  "mcpServers": {
    "grabmaps": {
      "transport": "streamable-http",
      "url": "https://mcp.techmavie.digital/grabmaps/mcp?api_key=usr_XXXXXXXX"
    }
  }
}

Cursor/Windsurf: Mismo formato en sus archivos de configuración MCP.

Demostración en vivo

Una instancia pública está disponible en:

https://mcp.techmavie.digital/grabmaps/mcp

Registre sus credenciales de GrabMaps + AWS con el Servicio de claves MCP para obtener su clave API usr_XXXXXXXX.

Despliegue en VPS

Arquitectura

Client (Claude, Cursor, Windsurf, etc.)
    ↓ HTTPS (usr_XXXXXXXX key)
https://mcp.techmavie.digital/grabmaps/mcp/usr_XXXXXXXX
    ↓
Nginx (SSL termination + reverse proxy)
    ↓ HTTP
Docker Container (port 8092 → 8080)
    ↓
GrabMaps MCP Server (Streamable HTTP Transport)
    ↓ resolves usr_ key
MCP Key Service → decrypted GrabMaps + AWS credentials
    ↓
AWS Location Service (GrabMaps)

Archivos de despliegue

Despliegue rápido

# On your VPS — ensure the shared Docker network exists
docker network create mcp-network  # only needed once

mkdir -p /opt/mcp-servers/grabmaps
cd /opt/mcp-servers/grabmaps
git clone https://github.com/hithereiamaliff/mcp-grabmaps.git .

# Set key-service env vars
cp .env.example .env
nano .env  # set KEY_SERVICE_URL and KEY_SERVICE_TOKEN

docker compose up -d --build

# Configure Nginx (add location block from deploy/nginx-mcp.conf)
sudo nano /etc/nginx/sites-available/mcp.techmavie.digital
sudo nginx -t
sudo systemctl reload nginx

Puntos finales

Firebase Analytics

El despliegue en VPS incluye la integración de Firebase Realtime Database para el almacenamiento de analíticas basado en la nube.

Características

• Almacenamiento dual: Firebase (primario) + copia de seguridad de archivos locales (respaldo)

• Seguimiento en tiempo real: Solicitudes, llamadas a herramientas, IP de clientes, agentes de usuario

• Panel visual: Panel de Chart.js en /analytics/dashboard

• Persistente: Las analíticas sobreviven a reinicios de contenedores y redespliegues

• Guardado automático: Guarda cada 60 segundos + en apagado ordenado

Datos de analíticas rastreados

• Total de solicitudes y llamadas a herramientas

• Solicitudes por método (GET, POST)

• Solicitudes por punto final (/, /health, /mcp, /analytics)

• Estadísticas de uso de herramientas

• Seguimiento de clientes (direcciones IP, agentes de usuario)

• Patrones de solicitud por hora

• Historial reciente de llamadas a herramientas

Configuración de Firebase

Consulte FIREBASE_SETUP.md para obtener instrucciones completas de configuración.

Configuración rápida:

# On VPS
cd /opt/mcp-servers/grabmaps
mkdir -p .credentials
nano .credentials/firebase-service-account.json  # Paste your Firebase service account JSON

# Copy to Docker volume
docker volume create grabmaps_firebase-credentials
docker run --rm \
  -v grabmaps_firebase-credentials:/credentials \
  -v $(pwd)/.credentials:/source:ro \
  alpine cp /source/firebase-service-account.json /credentials/

# Fix permissions
docker run --rm \
  -v grabmaps_firebase-credentials:/credentials \
  alpine chown -R 1001:1001 /credentials/

# Restart
docker compose down
docker compose up -d --build

Visualización de analíticas

• Panel: https://mcp.techmavie.digital/grabmaps/analytics/dashboard

• API JSON: https://mcp.techmavie.digital/grabmaps/analytics

• Consola de Firebase: https://console.firebase.google.com/ → Su proyecto → Realtime Database

Estructura de datos de Firebase

mcp-analytics/
  └── mcp-grabmaps/
      ├── serverStartTime: "2026-01-06T..."
      ├── totalRequests: 123
      ├── totalToolCalls: 45
      ├── requestsByMethod: {...}
      ├── requestsByEndpoint: {...}
      ├── toolCalls: {...}
      ├── recentToolCalls: [...]
      ├── clientsByIp: {...}
      ├── clientsByUserAgent: {...}
      ├── hourlyRequests: {...}
      └── lastUpdated: 1704470400000

Notas importantes para modelos de IA

Países admitidos

GrabMaps SOLO admite los siguientes ocho países en el sudeste asiático:

• Malasia (MYS)

• Singapur (SGP)

• Tailandia (THA)

• Myanmar (MMR)

• Camboya (KHM)

• Vietnam (VNM)

• Filipinas (PHL)

• Indonesia (IDN)

Los modelos de IA no deben intentar usar GrabMaps para ubicaciones fuera de estos países, ya que los resultados serán inexactos o inexistentes.

Requisitos de código de país

Al usar las funciones de la API de Lugares, los modelos de IA DEBEN analizar la consulta del usuario para determinar el país apropiado e incluir el código de país ISO de tres letras en todas las solicitudes:

{
  "query": "City Square Mall",
  "country": "SGP"  // SGP for Singapore, MYS for Malaysia, THA for Thailand, etc.
}

Ejemplos de códigos de país:

• Singapur: SGP

• Malasia: MYS

• Tailandia: THA

• Indonesia: IDN

• Filipinas: PHL

• Vietnam: VNM

Incluir el código de país es fundamental para devolver resultados de búsqueda precisos.

Este enfoque le permite probar la funcionalidad de Lugares y Rutas sin necesidad de configurar componentes de visualización de mapas.

Ejemplos de llamadas a la API

Geocodificación directa

const response = await fetch('http://localhost:3000/searchPlaceIndexForText', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: 'KLCC, Kuala Lumpur',
    country: 'my',
    maxResults: 5
  })
});

const data = await response.json();
console.log(data);

Calcular ruta

const response = await fetch('http://localhost:3000/calculateRoute', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    origin: {
      longitude: 101.6942371,
      latitude: 3.1516964
    },
    destination: {
      longitude: 101.7113,
      latitude: 3.1421
    },
    travelMode: 'Car'
  })
});

const data = await response.json();
console.log(data);

Integración con modelos de IA

Este servidor MCP se puede integrar con modelos de IA que admitan el Protocolo de Contexto de Modelo. Ejemplo de integración con un modelo de IA:

// Example of how an AI model would use this MCP server
const result = await mcpClient.call('grabmaps', 'searchPlaceIndexForText', {
  query: 'KLCC, Kuala Lumpur',
  country: 'my'
});

// The AI model can then use the result in its response
console.log(`The coordinates of KLCC are: ${result.results[0].coordinates.latitude}, ${result.results[0].coordinates.longitude}`);

Configuración de AWS Location Service

Antes de usar este servidor MCP, debe configurar los siguientes recursos en AWS Location Service:

1. Crear un índice de lugares con GrabMaps como proveedor de datos

2. Crear un mapa con GrabMaps como proveedor de datos

3. Crear una calculadora de rutas con GrabMaps como proveedor de datos

Limitaciones de los componentes de mapas y enfoque recomendado

Los componentes de la API de Mapas tienen ciertas limitaciones cuando se usan a través del servidor MCP:

• Los mosaicos de mapa devueltos por el punto final getMapTile son datos binarios codificados como cadenas base64

• Las pilas de fuentes para getMapGlyphs deben coincidir con las admitidas por GrabMaps a través de AWS Location Service

• Los nombres de archivo de sprites para getMapSprites deben seguir patrones regex específicos

• Los niveles máximos de zoom están restringidos (normalmente zoom máximo 14)

Enfoque recomendado:

• Para mapas: Use la integración directa con GrabMaps a través de MapLibre GL y AWS Location Service como se muestra en la demostración oficial

• Para lugares y rutas: Use el servidor MCP a través del entorno de pruebas de Smithery o llamadas directas a la API

Esta separación permite un rendimiento y una visualización óptimos mientras se sigue aprovechando el servidor MCP para la funcionalidad de Lugares y Rutas.

Demostración oficial de GrabMaps MapLibre GL

Se incluye una demostración completa que utiliza la integración oficial de GrabMaps con MapLibre GL en el directorio examples/official-map-demo. Esta demostración proporciona una interfaz de prueba completa para todos los componentes de GrabMaps:

• API de Lugares: Geocodificación directa/inversa y detalles de lugares

• API de Mapas: Mosaicos de mapa, descriptores de estilo, sprites y glifos

• API de Rutas: Cálculo de rutas y matriz de rutas

La demostración cuenta con una interfaz con pestañas para probar fácilmente diferentes componentes y proporciona comentarios detallados para cada llamada a la API.

Características clave

• Mapa interactivo que utiliza mosaicos de mapa oficiales de GrabMaps a través de MapLibre GL

• Interfaz con pestañas para probar diferentes componentes de GrabMaps

• Pruebas exhaustivas de todos los puntos finales de la API

• Clave API, región y nombres de recursos configurables

• Visualización de rutas, resultados de búsqueda y componentes de mapa

Para ejecutar la demostración:

# Start the MCP server
npm start

# Then open examples/official-map-demo/index.html in your browser

Consulte el README de la demostración oficial de mapas para obtener instrucciones de configuración y uso.

Pruebas

Se incluye un conjunto completo de pruebas en el directorio tests para verificar que todos los puntos finales funcionen correctamente. Para obtener instrucciones detalladas de prueba, ejemplos y consejos de solución de problemas, consulte el archivo TESTING.md.

Para ejecutar las pruebas:

# Start the MCP server in one terminal
npm start

# Run the test suite in another terminal
node tests/test-suite.js

Licencia

Este proyecto está bajo la Licencia MIT; consulte el archivo LICENSE para obtener más detalles.

Contribución

¡Las contribuciones son bienvenidas! No dude en enviar una solicitud de extracción (Pull Request).