GrabMaps MCP Server

GrabMaps MCP服务器

用于GrabMaps API集成的模型上下文协议（MCP）服务器，通过AWS定位服务提供对GrabMap服务的访问。

请注意，此MCP服务器 非 正式隶属于Grab、GrabMaps或AWS定位服务。

重要GrabMaps仅支持东南亚的八个国家。 - 🇲🇾 马来西亚（MYS） - 🇸🇬 新加坡（SGP） - 🇹🇭 泰国（THA） - 🇲🇲 缅甸（MMR） - 🇰🇭 柬埔寨（KHM） - 🇻🇳 越南（VNM） - 🇵🇭 菲律宾（PHL） - 🇮🇩 印度尼西亚（IDN） 这些国家以外的搜索请求将不会返回准确的结果。

特性

此MCP服务器通过两个主要类别提供对GrabMaps功能的访问：

地点行动（可通过MCP获得）

• 搜索地点索引文本：转发地理编码，按名称或地址查找地点
• 搜索地点索引位置：反向地理编码，按坐标查找地点
• 搜索地点索引建议：键入时获取位置建议
• GetPlace：检索特定地点的详细信息

路由操作（可通过MCP获得）

• 计算路线：计算带有航路点的点之间的路线
• 计算路由矩阵：计算多个起点和目的地之间的路线矩阵

分析和监控

• Firebase分析：使用Firebase实时数据库的基于云的分析存储
• 本地备份：自动本地文件备份作为回退
• 可视化仪表盘：使用Chart.js的实时分析仪表板
• 请求跟踪：按方法、端点、客户端IP和用户代理跟踪请求
• 工具调用跟踪：监控MCP工具的使用和性能

地图功能（需要AWS控制台）

备注：地图渲染功能不能通过MCP服务器直接使用。要查看和使用地图，请执行以下操作：

1. 转到AWS位置服务控制台
2. 查找“地图”部分，然后单击“尝试”按钮
3. 确保选择“Grab”作为提供商

要探索GrabMaps的数据覆盖范围，并在不登录AWS的情况下查看正在运行的地图，请访问： https://grabmaps.grab.com/explore-data-coverage

安装

来自NPM

npm install mcp-grabmaps

来自源头

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

配置

VPS/HTTP服务器（密钥服务模式）

HTTP服务器通过以下方式对用户进行身份验证 MCP密钥服务。用户向密钥服务注册他们的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. 使用中提供的示例测试地点和路由API调用 微笑_测试.md

方法3：自托管VPS部署

使用Docker和Nginx在您自己的VPS上部署MCP服务器。身份验证由 MCP密钥服务 --用户提供单个 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

客户端配置

克劳德桌面：

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

光标/风帆： MCP配置文件中的格式相同。

现场演示

公共实例可在以下网址获得：

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

在MCP密钥服务中注册您的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分析

VPS部署包括用于基于云的分析存储的Firebase实时数据库集成。

特性

• 双存储器：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接口: https://mcp.techmavie.digital/grabmaps/analytics
• Firebase控制台: https://console.firebase.google.com/ → 您的项目→ 实时数据库

Firebase数据结构

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

______________________________________________________________________

AI模型的重要注意事项

支持的国家

GrabMaps 仅 支持东南亚以下八个国家：

• 马来西亚（MYS）
• 新加坡（SGP）
• 泰国（THA）
• 缅甸（MMR）
• 柬埔寨（KHM）
• 越南（VNM）
• 菲律宾（PHL）
• 印度尼西亚（IDN）

人工智能模型不应尝试将GrabMaps用于这些国家以外的位置，因为结果将不准确或不存在。

国家代码要求

当使用Places API函数时，AI模型 必须 分析用户的查询以确定适当的国家，并在所有请求中包含三个字母的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服务器可以与支持模型上下文协议的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定位服务设置

在使用此MCP服务器之前，您需要在AWS位置服务中设置以下资源：

1. 使用GrabMaps作为数据提供者创建地点索引
2. 使用GrabMaps作为数据提供者创建地图
3. 使用GrabMaps作为数据提供者创建路线计算器

地图组件限制和推荐方法

当通过MCP服务器使用地图API组件时，这些组件具有某些限制：

• 返回的地图块 getMapTile 端点是编码为base64字符串的二进制数据
• 字体堆栈 getMapGlyphs 必须通过AWS定位服务与GrabMaps支持的服务相匹配
• 的Sprite文件名 getMapSprites 必须遵循特定的正则表达式模式
• 最大缩放级别受到限制（通常最大缩放14）

推荐方法：

• 对于地图：如官方演示所示，通过MapLibre GL和AWS定位服务与GrabMaps直接集成
• 对于地点和路线：通过Smithery游乐场或直接API调用使用MCP服务器

这种分离允许最佳性能和可视化，同时仍然利用MCP服务器实现地点和路线功能。

官方GrabMaps MapLibre GL演示

使用官方GrabMaps与MapLibre GL集成的全面演示包含在 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 目录，以验证所有终结点是否正常工作。有关详细的测试说明、示例和故障排除提示，请参阅 测试.md 文件。

要运行测试，请执行以下操作：

# Start the MCP server in one terminal
npm start

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

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

贡献

欢迎投稿！请随时提交拉取请求。