GrabMaps MCP 서버

AWS Location Service를 통해 GrabMaps 서비스에 대한 액세스를 제공하는 GrabMaps API 통합용 Model Context Protocol(MCP) 서버입니다.

이 MCP 서버는 Grab, GrabMaps 또는 AWS Location Service와 공식적으로 제휴되어 있지 않습니다.

중요: GrabMaps는 동남아시아의 8개 국가만 지원합니다.

• 🇲🇾 말레이시아 (MYS)

• 🇸🇬 싱가포르 (SGP)

• 🇹🇭 태국 (THA)

• 🇲🇲 미얀마 (MMR)

• 🇰🇭 캄보디아 (KHM)

• 🇻🇳 베트남 (VNM)

• 🇵🇭 필리핀 (PHL)

• 🇮🇩 인도네시아 (IDN)

이 국가들 이외의 지역에 대한 검색 요청은 정확한 결과를 반환하지 않습니다.

기능

이 MCP 서버는 두 가지 주요 범주를 통해 GrabMaps 기능을 제공합니다:

장소 작업 (MCP를 통해 사용 가능)

• SearchPlaceIndexForText: 이름이나 주소로 장소를 찾는 순방향 지오코딩

• SearchPlaceIndexForPosition: 좌표로 장소를 찾는 역방향 지오코딩

• SearchPlaceIndexForSuggestions: 입력하는 동안 장소 제안 받기

• GetPlace: 특정 장소에 대한 상세 정보 검색

경로 작업 (MCP를 통해 사용 가능)

• CalculateRoute: 경유지를 포함한 지점 간 경로 계산

• CalculateRouteMatrix: 여러 출발지와 목적지 간의 경로 행렬 계산

분석 및 모니터링

• Firebase Analytics: Firebase 실시간 데이터베이스를 사용한 클라우드 기반 분석 저장소

• 로컬 백업: 대체 수단으로 자동 로컬 파일 백업

• 시각적 대시보드: Chart.js를 사용한 실시간 분석 대시보드

• 요청 추적: 메서드, 엔드포인트, 클라이언트 IP 및 사용자 에이전트별 요청 추적

• 도구 호출 추적: MCP 도구 사용량 및 성능 모니터링

지도 기능 (AWS 콘솔 필요)

참고: 지도 렌더링 기능은 MCP 서버를 통해 직접 사용할 수 없습니다. 지도를 보고 사용하려면:

1. AWS Location Service 콘솔로 이동합니다.

2. 지도 섹션을 찾아 "Try it" 버튼을 클릭합니다.

3. 공급자로 "Grab"이 선택되어 있는지 확인합니다.

AWS에 로그인하지 않고 GrabMaps 데이터 범위를 살펴보고 지도를 실제로 보려면 다음을 방문하세요: https://grabmaps.grab.com/explore-data-coverage

Related MCP server: Google Maps MCP Server

설치

NPM에서

npm install mcp-grabmaps

소스에서

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

구성

VPS / HTTP 서버 (키 서비스 모드)

HTTP 서버는 MCP Key Service를 통해 사용자를 인증합니다. 사용자는 키 서비스에 GrabMaps + AWS 자격 증명을 등록하고 단일 usr_XXXXXXXX API 키를 받습니다.

.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 / 로컬 개발

Smithery 또는 로컬 개발을 통해 실행할 때 GrabMaps 및 AWS 자격 증명은 (키 서비스가 아닌) Smithery SDK 구성 스키마를 통해 직접 제공됩니다. .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

사용법

방법 1: 로컬에서 실행

# Development mode
npm run dev

# Production mode
npm run build
npm start

방법 2: Smithery와 함께 사용

# Run in development mode
npm run smithery:dev

# Build for production
npm run smithery:build

# Deploy to Smithery
npm run smithery:deploy

Smithery 플레이그라운드에서 테스트

장소 및 경로 API를 테스트하는 최상의 경험을 위해 Smithery 플레이그라운드 사용을 권장합니다:

1. 로컬에서 MCP 서버를 시작합니다: npm run dev

2. Smithery 플레이그라운드(https://smithery.ai/playground)를 엽니다.

3. 로컬 MCP 서버에 연결합니다: http://localhost:3000

4. SMITHERY_TESTING.md에 제공된 예제를 사용하여 장소 및 경로 API 호출을 테스트합니다.

방법 3: 자체 호스팅 VPS 배포

Docker와 Nginx를 사용하여 자신의 VPS에 MCP 서버를 배포합니다. 인증은 MCP Key Service에 의해 처리됩니다. 사용자는 원시 자격 증명 대신 단일 usr_XXXXXXXX API 키를 제공합니다.

VPS URL 형식

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

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

클라이언트 구성

Claude Desktop:

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

Cursor/Windsurf: MCP 구성 파일에서 동일한 형식.

라이브 데모

공개 인스턴스는 다음에서 사용할 수 있습니다:

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

MCP Key Service에 GrabMaps + AWS 자격 증명을 등록하여 usr_XXXXXXXX API 키를 받으세요.

VPS 배포

아키텍처

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)

배포 파일

빠른 배포

# 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

엔드포인트

Firebase Analytics

VPS 배포에는 클라우드 기반 분석 저장을 위한 Firebase 실시간 데이터베이스 통합이 포함되어 있습니다.

기능

• 이중 저장소: Firebase(기본) + 로컬 파일 백업(대체)

• 실시간 추적: 요청, 도구 호출, 클라이언트 IP, 사용자 에이전트

• 시각적 대시보드: /analytics/dashboard에서 Chart.js 대시보드 제공

• 영구적: 컨테이너 재시작 및 재배포 후에도 분석 데이터 유지

• 자동 저장: 60초마다 및 정상 종료 시 저장

추적되는 분석 데이터

• 총 요청 및 도구 호출 수

• 메서드별 요청 (GET, POST)

• 엔드포인트별 요청 (/, /health, /mcp, /analytics)

• 도구 사용 통계

• 클라이언트 추적 (IP 주소, 사용자 에이전트)

• 시간별 요청 패턴

• 최근 도구 호출 기록

Firebase 설정

전체 설정 지침은 FIREBASE_SETUP.md를 참조하세요.

빠른 설정:

# 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

분석 보기

• 대시보드: https://mcp.techmavie.digital/grabmaps/analytics/dashboard

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

• Firebase 콘솔: https://console.firebase.google.com/ → 프로젝트 → Realtime Database

Firebase 데이터 구조

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

AI 모델을 위한 중요 참고 사항

지원 국가

GrabMaps는 동남아시아의 다음 8개 국가만 지원합니다:

• 말레이시아 (MYS)

• 싱가포르 (SGP)

• 태국 (THA)

• 미얀마 (MMR)

• 캄보디아 (KHM)

• 베트남 (VNM)

• 필리핀 (PHL)

• 인도네시아 (IDN)

AI 모델은 이 국가들 이외의 위치에 대해 GrabMaps를 사용하려고 시도해서는 안 됩니다. 결과가 부정확하거나 존재하지 않기 때문입니다.

국가 코드 요구 사항

장소 API 기능을 사용할 때 AI 모델은 사용자의 쿼리를 분석하여 적절한 국가를 결정하고 모든 요청에 3자리 ISO 국가 코드를 포함해야 합니다:

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

국가 코드 예시:

• 싱가포르: SGP

• 말레이시아: MYS

• 태국: THA

• 인도네시아: IDN

• 필리핀: PHL

• 베트남: VNM

정확한 검색 결과를 반환하려면 국가 코드를 포함하는 것이 중요합니다.

이 접근 방식을 사용하면 지도 시각화 구성 요소를 설정할 필요 없이 장소 및 경로 기능을 테스트할 수 있습니다.

API 호출 예시

순방향 지오코딩

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

경로 계산

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

AI 모델과 통합

이 MCP 서버는 Model Context Protocol을 지원하는 AI 모델과 통합할 수 있습니다. AI 모델과의 통합 예시:

// 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 설정

이 MCP 서버를 사용하기 전에 AWS Location Service에서 다음 리소스를 설정해야 합니다:

1. GrabMaps를 데이터 공급자로 하는 장소 인덱스(Place Index) 생성

2. GrabMaps를 데이터 공급자로 하는 지도(Map) 생성

3. GrabMaps를 데이터 공급자로 하는 경로 계산기(Route Calculator) 생성

지도 구성 요소 제한 사항 및 권장 접근 방식

지도 API 구성 요소는 MCP 서버를 통해 사용할 때 특정 제한 사항이 있습니다:

• getMapTile 엔드포인트에서 반환된 지도 타일은 base64 문자열로 인코딩된 이진 데이터입니다.

• getMapGlyphs용 글꼴 스택은 AWS Location Service를 통해 GrabMaps에서 지원하는 것과 일치해야 합니다.

• getMapSprites용 스프라이트 파일 이름은 특정 정규식 패턴을 따라야 합니다.

• 최대 줌 레벨이 제한됩니다 (일반적으로 최대 줌 14).

권장 접근 방식:

• 지도: 공식 데모에 표시된 대로 MapLibre GL 및 AWS Location Service를 통해 GrabMaps와 직접 통합하여 사용하세요.

• 장소 및 경로: Smithery 플레이그라운드 또는 직접 API 호출을 통해 MCP 서버를 사용하세요.

이러한 분리를 통해 장소 및 경로 기능에 대해서는 MCP 서버를 활용하면서도 최적의 성능과 시각화를 얻을 수 있습니다.

공식 GrabMaps MapLibre GL 데모

MapLibre GL과 공식 GrabMaps 통합을 사용하는 포괄적인 데모가 examples/official-map-demo 디렉토리에 포함되어 있습니다. 이 데모는 모든 GrabMaps 구성 요소에 대한 완전한 테스트 인터페이스를 제공합니다:

• 장소 API: 순방향/역방향 지오코딩 및 장소 세부 정보

• 지도 API: 지도 타일, 스타일 설명자, 스프라이트 및 글리프

• 경로 API: 경로 계산 및 경로 행렬

이 데모는 다양한 구성 요소를 쉽게 테스트할 수 있는 탭 인터페이스를 제공하며 각 API 호출에 대한 상세한 피드백을 제공합니다.

주요 기능

• MapLibre GL을 통해 공식 GrabMaps 지도 타일을 사용하는 대화형 지도

• 다양한 GrabMaps 구성 요소를 테스트하기 위한 탭 인터페이스

• 모든 API 엔드포인트에 대한 포괄적인 테스트

• 구성 가능한 API 키, 지역 및 리소스 이름

• 경로, 검색 결과 및 지도 구성 요소의 시각적 표시

데모를 실행하려면:

# Start the MCP server
npm start

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

설정 및 사용 지침은 공식 지도 데모 README를 참조하세요.

테스트

모든 엔드포인트가 올바르게 작동하는지 확인하기 위해 tests 디렉토리에 포괄적인 테스트 제품군이 포함되어 있습니다. 자세한 테스트 지침, 예제 및 문제 해결 팁은 TESTING.md 파일을 참조하세요.

테스트를 실행하려면:

# Start the MCP server in one terminal
npm start

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

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다. 자세한 내용은 LICENSE 파일을 참조하세요.

기여

기여를 환영합니다! 자유롭게 Pull Request를 제출해 주세요.