GrabMaps MCP-Server

Ein Model Context Protocol (MCP)-Server für die GrabMaps-API-Integration, der Zugriff auf GrabMaps-Dienste über den AWS Location Service bietet.

Bitte beachten Sie, dass dieser MCP-Server NICHT offiziell mit Grab, GrabMaps oder dem AWS Location Service verbunden ist.

Wichtig: GrabMaps unterstützt nur acht Länder in Südostasien.

• 🇲🇾 Malaysia (MYS)

• 🇸🇬 Singapur (SGP)

• 🇹🇭 Thailand (THA)

• 🇲🇲 Myanmar (MMR)

• 🇰🇭 Kambodscha (KHM)

• 🇻🇳 Vietnam (VNM)

• 🇵🇭 Philippinen (PHL)

• 🇮🇩 Indonesien (IDN)

Suchanfragen außerhalb dieser Länder liefern keine genauen Ergebnisse.

Funktionen

Dieser MCP-Server bietet Zugriff auf die GrabMaps-Funktionalität über zwei Hauptkategorien:

Orte-Aktionen (Verfügbar über MCP)

• SearchPlaceIndexForText: Vorwärts-Geokodierung, um Orte nach Name oder Adresse zu finden

• SearchPlaceIndexForPosition: Rückwärts-Geokodierung, um Orte anhand von Koordinaten zu finden

• SearchPlaceIndexForSuggestions: Erhalten Sie Ort-Vorschläge während der Eingabe

• GetPlace: Abrufen detaillierter Informationen zu einem bestimmten Ort

Routen-Aktionen (Verfügbar über MCP)

• CalculateRoute: Routen zwischen Punkten mit Wegpunkten berechnen

• CalculateRouteMatrix: Eine Matrix von Routen zwischen mehreren Start- und Zielpunkten berechnen

Analytik & Überwachung

• Firebase Analytics: Cloud-basierter Analytik-Speicher mit Firebase Realtime Database

• Lokales Backup: Automatisches lokales Datei-Backup als Fallback

• Visuelles Dashboard: Echtzeit-Analytik-Dashboard mit Chart.js

• Anfrage-Tracking: Verfolgen Sie Anfragen nach Methode, Endpunkt, Client-IP und User-Agent

• Tool-Call-Tracking: Überwachen Sie die Nutzung und Leistung von MCP-Tools

Karten-Funktionalität (Erfordert AWS-Konsole)

Hinweis: Die Karten-Rendering-Funktionalität ist nicht direkt über den MCP-Server verfügbar. Um Karten anzuzeigen und zu nutzen:

1. Gehen Sie zur AWS Location Service-Konsole

2. Suchen Sie den Abschnitt "Karten" (Maps) und klicken Sie auf die Schaltfläche "Ausprobieren" (Try it)

3. Stellen Sie sicher, dass "Grab" als Anbieter ausgewählt ist

Um die Abdeckung der GrabMaps-Daten zu erkunden und die Karten in Aktion zu sehen, ohne sich bei AWS anzumelden, besuchen Sie: https://grabmaps.grab.com/explore-data-coverage

Related MCP server: Google Maps MCP Server

Installation

Von NPM

npm install mcp-grabmaps

Von der Quelle

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

Konfiguration

VPS / HTTP-Server (Key-Service-Modus)

Der HTTP-Server authentifiziert Benutzer über den MCP Key Service. Benutzer registrieren ihre GrabMaps + AWS-Anmeldedaten beim Key-Service und erhalten einen einzelnen usr_XXXXXXXX API-Schlüssel.

Erstellen Sie eine .env-Datei:

# 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 / Lokale Entwicklung

Bei der Ausführung über Smithery oder in der lokalen Entwicklung werden GrabMaps- und AWS-Anmeldedaten direkt über das Smithery SDK-Konfigurationsschema bereitgestellt (nicht über den Key-Service). Setzen Sie diese in der .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

Verwendung

Methode 1: Lokal ausführen

# Development mode
npm run dev

# Production mode
npm run build
npm start

Methode 2: Verwendung mit Smithery

# Run in development mode
npm run smithery:dev

# Build for production
npm run smithery:build

# Deploy to Smithery
npm run smithery:deploy

Testen im Smithery Playground

Für die beste Erfahrung beim Testen der Orte- und Routen-APIs empfehlen wir die Verwendung des Smithery Playgrounds:

1. Starten Sie Ihren MCP-Server lokal: npm run dev

2. Öffnen Sie den Smithery Playground unter: https://smithery.ai/playground

3. Verbinden Sie sich mit Ihrem lokalen MCP-Server: http://localhost:3000

4. Testen Sie die Orte- und Routen-API-Aufrufe mithilfe der bereitgestellten Beispiele in SMITHERY_TESTING.md

Methode 3: Selbstgehostete VPS-Bereitstellung

Stellen Sie den MCP-Server auf Ihrem eigenen VPS mit Docker und Nginx bereit. Die Authentifizierung wird vom MCP Key Service übernommen – Benutzer geben einen einzelnen usr_XXXXXXXX API-Schlüssel anstelle von Rohdaten an.

VPS-URL-Format

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

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

Client-Konfiguration

Claude Desktop:

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

Cursor/Windsurf: Gleiches Format in deren MCP-Konfigurationsdateien.

Live-Demo

Eine öffentliche Instanz ist verfügbar unter:

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

Registrieren Sie Ihre GrabMaps + AWS-Anmeldedaten beim MCP Key Service, um Ihren usr_XXXXXXXX API-Schlüssel zu erhalten.

VPS-Bereitstellung

Architektur

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)

Bereitstellungsdateien

Schnelle Bereitstellung

# 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

Endpunkte

Firebase Analytics

Die VPS-Bereitstellung beinhaltet eine Firebase Realtime Database-Integration für cloud-basierten Analytik-Speicher.

Funktionen

• Dualer Speicher: Firebase (primär) + lokales Datei-Backup (Fallback)

• Echtzeit-Tracking: Anfragen, Tool-Aufrufe, Client-IPs, User-Agents

• Visuelles Dashboard: Chart.js-Dashboard unter /analytics/dashboard

• Persistenz: Analytik überlebt Container-Neustarts und erneute Bereitstellungen

• Automatisches Speichern: Speichert alle 60 Sekunden + bei ordnungsgemäßem Herunterfahren

Verfolgte Analytik-Daten

• Gesamtzahl der Anfragen und Tool-Aufrufe

• Anfragen nach Methode (GET, POST)

• Anfragen nach Endpunkt (/, /health, /mcp, /analytics)

• Statistiken zur Tool-Nutzung

• Client-Tracking (IP-Adressen, User-Agents)

• Stündliche Anfrage-Muster

• Verlauf der letzten Tool-Aufrufe

Firebase-Einrichtung

Siehe FIREBASE_SETUP.md für vollständige Einrichtungsanweisungen.

Schnelleinrichtung:

# 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

Analytik anzeigen

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

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

• Firebase-Konsole: https://console.firebase.google.com/ → Ihr Projekt → Realtime Database

Firebase-Datenstruktur

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

Wichtige Hinweise für KI-Modelle

Unterstützte Länder

GrabMaps unterstützt NUR die folgenden acht Länder in Südostasien:

• Malaysia (MYS)

• Singapur (SGP)

• Thailand (THA)

• Myanmar (MMR)

• Kambodscha (KHM)

• Vietnam (VNM)

• Philippinen (PHL)

• Indonesien (IDN)

KI-Modelle sollten nicht versuchen, GrabMaps für Standorte außerhalb dieser Länder zu verwenden, da die Ergebnisse ungenau oder nicht vorhanden sein werden.

Anforderungen an Ländercodes

Bei der Verwendung der Places-API-Funktionen MÜSSEN KI-Modelle die Anfrage des Benutzers analysieren, um das entsprechende Land zu bestimmen, und den dreistelligen ISO-Ländercode in alle Anfragen einbeziehen:

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

Beispiele für Ländercodes:

• Singapur: SGP

• Malaysia: MYS

• Thailand: THA

• Indonesien: IDN

• Philippinen: PHL

• Vietnam: VNM

Die Einbeziehung des Ländercodes ist entscheidend für die Rückgabe genauer Suchergebnisse.

Dieser Ansatz ermöglicht es Ihnen, die Orte- und Routen-Funktionalität zu testen, ohne Karten-Visualisierungskomponenten einrichten zu müssen.

Beispiel-API-Aufrufe

Vorwärts-Geokodierung

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);

Route berechnen

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);

Integration mit KI-Modellen

Dieser MCP-Server kann in KI-Modelle integriert werden, die das Model Context Protocol unterstützen. Beispiel für die Integration mit einem KI-Modell:

// 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}`);

AWS Location Service-Einrichtung

Bevor Sie diesen MCP-Server verwenden, müssen Sie die folgenden Ressourcen im AWS Location Service einrichten:

1. Erstellen Sie einen Place Index mit GrabMaps als Datenanbieter

2. Erstellen Sie eine Karte mit GrabMaps als Datenanbieter

3. Erstellen Sie einen Routenrechner mit GrabMaps als Datenanbieter

Einschränkungen der Kartenkomponente und empfohlener Ansatz

Die Karten-API-Komponenten haben bestimmte Einschränkungen, wenn sie über den MCP-Server verwendet werden:

• Kartenkacheln, die vom getMapTile-Endpunkt zurückgegeben werden, sind Binärdaten, die als Base64-Strings kodiert sind

• Font-Stacks für getMapGlyphs müssen mit denen übereinstimmen, die von GrabMaps über den AWS Location Service unterstützt werden

• Sprite-Dateinamen für getMapSprites müssen bestimmten Regex-Mustern folgen

• Maximale Zoomstufen sind eingeschränkt (normalerweise max. Zoom 14)

Empfohlener Ansatz:

• Für Karten: Verwenden Sie die direkte Integration mit GrabMaps über MapLibre GL und den AWS Location Service, wie in der offiziellen Demo gezeigt

• Für Orte und Routen: Verwenden Sie den MCP-Server über den Smithery Playground oder direkte API-Aufrufe

Diese Trennung ermöglicht eine optimale Leistung und Visualisierung, während der MCP-Server weiterhin für die Orte- und Routen-Funktionalität genutzt wird.

Offizielle GrabMaps MapLibre GL Demo

Eine umfassende Demo, die die offizielle GrabMaps-Integration mit MapLibre GL verwendet, ist im Verzeichnis examples/official-map-demo enthalten. Diese Demo bietet eine vollständige Testoberfläche für alle GrabMaps-Komponenten:

• Places API: Vorwärts-/Rückwärts-Geokodierung und Ort-Details

• Maps API: Kartenkacheln, Stil-Deskriptoren, Sprites und Glyphen

• Routes API: Routenberechnung und Routenmatrix

Die Demo bietet eine Registerkarten-Oberfläche für einfaches Testen verschiedener Komponenten und liefert detailliertes Feedback für jeden API-Aufruf.

Hauptfunktionen

• Interaktive Karte mit offiziellen GrabMaps-Kartenkacheln über MapLibre GL

• Registerkarten-Oberfläche zum Testen verschiedener GrabMaps-Komponenten

• Umfassendes Testen aller API-Endpunkte

• Konfigurierbarer API-Schlüssel, Region und Ressourcennamen

• Visuelle Darstellung von Routen, Suchergebnissen und Kartenkomponenten

So führen Sie die Demo aus:

# Start the MCP server
npm start

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

Siehe die Offizielle Karten-Demo README für Einrichtungs- und Nutzungshinweise.

Testen

Eine umfassende Testsuite ist im Verzeichnis tests enthalten, um zu überprüfen, ob alle Endpunkte korrekt funktionieren. Für detaillierte Testanweisungen, Beispiele und Tipps zur Fehlerbehebung lesen Sie bitte die Datei TESTING.md.

So führen Sie die Tests aus:

# Start the MCP server in one terminal
npm start

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

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert - siehe die LICENSE-Datei für Details.

Mitwirken

Beiträge sind willkommen! Bitte zögern Sie nicht, einen Pull Request einzureichen.