GrabMaps MCPサーバー

GrabMaps API統合のためのModel Context Protocol (MCP) サーバーであり、AWS Location Serviceを通じてGrabMapsサービスへのアクセスを提供します。

このMCPサーバーは、Grab、GrabMaps、またはAWS Location Serviceとは公式に提携していませんのでご注意ください。

重要: GrabMapsは東南アジアの8カ国のみをサポートしています。

• 🇲🇾 マレーシア (MYS)

• 🇸🇬 シンガポール (SGP)

• 🇹🇭 タイ (THA)

• 🇲🇲 ミャンマー (MMR)

• 🇰🇭 カンボジア (KHM)

• 🇻🇳 ベトナム (VNM)

• 🇵🇭 フィリピン (PHL)

• 🇮🇩 インドネシア (IDN)

これらの国以外での検索リクエストは、正確な結果を返しません。

機能

このMCPサーバーは、主に2つのカテゴリを通じてGrabMaps機能へのアクセスを提供します。

場所アクション (MCP経由で利用可能)

• SearchPlaceIndexForText: 名前や住所から場所を検索するフォワードジオコーディング

• SearchPlaceIndexForPosition: 座標から場所を検索するリバースジオコーディング

• SearchPlaceIndexForSuggestions: 入力中に場所の候補を取得する

• GetPlace: 特定の場所に関する詳細情報を取得する

ルートアクション (MCP経由で利用可能)

• CalculateRoute: 経由地を含む地点間のルートを計算する

• CalculateRouteMatrix: 複数の出発地と目的地の間のルート行列を計算する

分析と監視

• Firebase Analytics: Firebase Realtime Databaseを使用したクラウドベースの分析ストレージ

• ローカルバックアップ: フォールバックとしての自動ローカルファイルバックアップ

• ビジュアルダッシュボード: Chart.jsを使用したリアルタイム分析ダッシュボード

• リクエスト追跡: メソッド、エンドポイント、クライアントIP、ユーザーエージェントによるリクエストの追跡

• ツール呼び出し追跡: MCPツールの使用状況とパフォーマンスの監視

地図機能 (AWSコンソールが必要)

注意: 地図のレンダリング機能は、MCPサーバーを通じて直接利用することはできません。地図を表示および使用するには：

1. AWS Location Serviceコンソールに移動します

2. 「Maps」セクションを探し、「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 Playgroundでのテスト

PlacesおよびRoutes APIをテストする最適な体験のために、Smithery playgroundの使用を推奨します：

1. ローカルでMCPサーバーを起動します: npm run dev

2. Smithery playground (https://smithery.ai/playground) を開きます

3. ローカルのMCPサーバーに接続します: http://localhost:3000

4. SMITHERY_TESTING.md にある提供された例を使用して、PlacesおよびRoutes 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

GrabMaps + AWSの資格情報をMCP Key Serviceに登録して、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 Realtime Database統合が含まれています。

機能

• デュアルストレージ: 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を使用しようとしないでください。結果が不正確になるか、存在しないためです。

国コードの要件

Places 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

正確な検索結果を返すためには、国コードを含めることが不可欠です。

このアプローチにより、地図視覚化コンポーネントを設定することなく、PlacesおよびRoutes機能をテストできます。

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 playgroundまたは直接API呼び出しを通じてMCPサーバーを使用してください

この分離により、場所とルート機能にはMCPサーバーを活用しつつ、最適なパフォーマンスと視覚化を実現できます。

公式GrabMaps MapLibre GLデモ

MapLibre GLとGrabMapsの公式統合を使用した包括的なデモが examples/official-map-demo ディレクトリに含まれています。このデモは、すべてのGrabMapsコンポーネントの完全なテストインターフェースを提供します：

• Places API: フォワード/リバースジオコーディングおよび場所の詳細

• Maps API: 地図タイル、スタイル記述子、スプライト、グリフ

• Routes 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

設定と使用方法については、Official Map Demo 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 ファイルを参照してください。

貢献

貢献を歓迎します！お気軽にプルリクエストを送信してください。