Skip to main content
Glama
GrabMaps MCP Server

GrabMaps MCP Server

GrabMaps MCP Server

Сервер Model Context Protocol (MCP) для интеграции с API GrabMaps, предоставляющий доступ к сервисам GrabMaps через AWS Location Service.

Обратите внимание, что этот MCP-сервер НЕ является официально аффилированным с Grab, GrabMaps или AWS Location Service.

Важно: GrabMaps поддерживает только восемь стран Юго-Восточной Азии.

  • 🇲🇾 Малайзия (MYS)

  • 🇸🇬 Сингапур (SGP)

  • 🇹🇭 Таиланд (THA)

  • 🇲🇲 Мьянма (MMR)

  • 🇰🇭 Камбоджа (KHM)

  • 🇻🇳 Вьетнам (VNM)

  • 🇵🇭 Филиппины (PHL)

  • 🇮🇩 Индонезия (IDN)

Поисковые запросы за пределами этих стран не дадут точных результатов.

Функции

Этот MCP-сервер предоставляет доступ к функциональности 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"

Чтобы изучить покрытие данных GrabMaps и увидеть карты в действии без входа в AWS, посетите: 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 в службе ключей и получают единый API-ключ usr_XXXXXXXX.

Создайте файл .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

Переменная

Обязательно

Описание

KEY_SERVICE_URL

Да (HTTP)

Конечная точка разрешения MCP Key Service

KEY_SERVICE_TOKEN

Да (HTTP)

Токен Bearer для аутентификации в службе ключей

PLACE_INDEX_NAME

Нет

Имя индекса мест AWS (по умолчанию: explore.place.Grab)

MAP_NAME

Нет

Имя карты AWS (по умолчанию: explore.map.Grab)

ROUTE_CALCULATOR_NAME

Нет

Имя калькулятора маршрутов AWS (по умолчанию: explore.route-calculator.Grab)

PORT

Нет

Порт сервера (по умолчанию: 3000)

Smithery / Локальная разработка

При запуске через Smithery или локальной разработке учетные данные GrabMaps и AWS предоставляются напрямую через схему конфигурации SDK Smithery (не через службу ключей). Установите их в .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

Для наилучшего тестирования API мест и маршрутов мы рекомендуем использовать Smithery playground:

  1. Запустите ваш MCP-сервер локально: npm run dev

  2. Откройте Smithery playground по адресу: https://smithery.ai/playground

  3. Подключитесь к вашему локальному MCP-серверу: http://localhost:3000

  4. Протестируйте вызовы API мест и маршрутов, используя примеры, приведенные в SMITHERY_TESTING.md

Способ 3: Развертывание на собственном VPS

Разверните MCP-сервер на своем VPS с помощью Docker и Nginx. Аутентификация обрабатывается MCP Key Service — пользователи предоставляют один API-ключ usr_XXXXXXXX вместо необработанных учетных данных.

Формат URL для VPS

# 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, чтобы получить свой API-ключ usr_XXXXXXXX.


Развертывание на 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)

Файлы развертывания

Файл

Описание

src/http-server.ts

HTTP-сервер с потоковой передачей HTTP

Dockerfile

Конфигурация контейнера для VPS

docker-compose.yml

Оркестрация Docker (порт 8092)

deploy/nginx-mcp.conf

Конфигурация обратного прокси-сервера Nginx

.github/workflows/deploy-vps.yml

Автоматическое развертывание через GitHub Actions

Быстрое развертывание

# 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

Конечные точки

Конечная точка

Описание

/

Информация о сервере и инструкции по использованию

/health

Проверка работоспособности со статусом Firebase

/mcp?api_key=usr_...

Конечная точка MCP (аутентификация через параметры запроса)

/mcp/usr_...

Конечная точка MCP (аутентификация на основе пути)

/analytics

Данные аналитики (JSON)

/analytics/dashboard

Визуальная панель аналитики

/.well-known/mcp/server-card.json

Обнаружение MCP-сервера

/.well-known/mcp-config

Схема конфигурации сеанса MCP


Firebase Analytics

Развертывание на VPS включает интеграцию с Firebase Realtime Database для облачного хранения аналитики.

Функции

  • Двойное хранилище: Firebase (основное) + локальное резервное копирование файлов (резервное)

  • Отслеживание в реальном времени: Запросы, вызовы инструментов, IP-адреса клиентов, агенты пользователей

  • Визуальная панель мониторинга: Панель мониторинга Chart.js по адресу /analytics/dashboard

  • Постоянство: Аналитика сохраняется после перезапуска контейнера и повторных развертываний

  • Автосохранение: Сохранение каждые 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

Важные примечания для моделей ИИ

Поддерживаемые страны

GrabMaps поддерживает ТОЛЬКО следующие восемь стран Юго-Восточной Азии:

  • Малайзия (MYS)

  • Сингапур (SGP)

  • Таиланд (THA)

  • Мьянма (MMR)

  • Камбоджа (KHM)

  • Вьетнам (VNM)

  • Филиппины (PHL)

  • Индонезия (IDN)

Модели ИИ не должны пытаться использовать GrabMaps для местоположений за пределами этих стран, так как результаты будут неточными или отсутствующими.

Требования к коду страны

При использовании функций API мест модели ИИ ДОЛЖНЫ анализировать запрос пользователя, чтобы определить соответствующую страну, и включать трехбуквенный код страны 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);

Интеграция с моделями ИИ

Этот MCP-сервер можно интегрировать с моделями ИИ, поддерживающими протокол Model Context Protocol. Пример интеграции с моделью ИИ:

// 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. Создайте индекс мест (Place Index) с GrabMaps в качестве поставщика данных

  2. Создайте карту (Map) с GrabMaps в качестве поставщика данных

  3. Создайте калькулятор маршрутов (Route Calculator) с GrabMaps в качестве поставщика данных

Ограничения компонентов карты и рекомендуемый подход

Компоненты API карт имеют определенные ограничения при использовании через MCP-сервер:

  • Тайлы карт, возвращаемые конечной точкой getMapTile, представляют собой двоичные данные, закодированные как строки base64

  • Стеки шрифтов для getMapGlyphs должны соответствовать тем, которые поддерживаются GrabMaps через AWS Location Service

  • Имена файлов спрайтов для getMapSprites должны соответствовать определенным шаблонам regex

  • Максимальные уровни масштабирования ограничены (обычно макс. масштаб 14)

Рекомендуемый подход:

  • Для карт: Используйте прямую интеграцию с GrabMaps через MapLibre GL и AWS Location Service, как показано в официальной демонстрации

  • Для мест и маршрутов: Используйте MCP-сервер через Smithery playground или прямые вызовы API

Такое разделение обеспечивает оптимальную производительность и визуализацию, при этом используя MCP-сервер для функциональности мест и маршрутов.

Официальная демонстрация GrabMaps MapLibre GL

Комплексная демонстрация с использованием официальной интеграции GrabMaps с MapLibre GL включена в каталог examples/official-map-demo. Эта демонстрация предоставляет полный интерфейс тестирования для всех компонентов GrabMaps:

  • API мест: Прямое/обратное геокодирование и подробная информация о местах

  • API карт: Тайлы карт, дескрипторы стилей, спрайты и глифы

  • API маршрутов: Расчет маршрута и матрица маршрутов

Демонстрация оснащена интерфейсом с вкладками для легкого тестирования различных компонентов и предоставляет подробную обратную связь для каждого вызова API.

Ключевые особенности

  • Интерактивная карта с использованием официальных тайлов карт GrabMaps через MapLibre GL

  • Интерфейс с вкладками для тестирования различных компонентов 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • -
      license
      A
      quality
      Not graded
      maintenance
      Enables users to access Naver Maps API functionality including directions, place search, geocoding, and reverse geocoding through a Model Context Protocol server.
      4
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides access to Google Maps functionality including places search, geocoding, directions, distance calculations, elevation data, and static map generation through the Model Context Protocol interface.
      4
      MIT