quantaroute-geocoder

QuantaRoute MCP 服务

一个模型上下文协议（MCP）服务，通过 QuantaRoute Geocoding API 为 AI 助手（Claude Desktop、Cursor 等）提供强大的地理编码、位置查询和 DigiPin 处理功能。

软件包：@quantaroute/mcp-server（面向 AI Agent 的 MCP Server）
SDK：quantaroute-geocoding（Node.js/TypeScript SDK）

✅ 与 Claude Desktop 和 Cursor 完全兼容

功能

🗺️ 地理编码工具

• 对地址进行地理编码，获取 DigiPin 编码和坐标
• 反向地理编码 DigiPin 编码，获取地址
• 将坐标转换为 DigiPin 编码
• 验证 DigiPin 格式和位置
• 批量地理编码多个地址（最多 100 个）
• 自动补全地址建议

🚀 结合 Nominatim + 邮政编码 + Digipin 的革新性位置查询

• 根据坐标查询行政边界（邮政编码、州、分区、地点）
• 根据 DigiPin 编码查询
• 批量查询多个位置
• 查找指定半径内的邻近边界[即将推出……]
• 可访问印度各地 36,000 多个邮政边界

📊 实用工具

• 获取 API 使用量统计
• 获取位置统计信息（边界、州、分区）
• 检查 API 健康状态

安装

此 MCP 服务兼容 Claude Desktop 和 Cursor。请按照下方对应平台的说明操作。

适用于 Claude Desktop

1. 找到 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件并添加：

{
  "mcpServers": {
    "quantaroute": {
      "command": "npx",
      "args": [
        "-y",
        "@quantaroute/mcp-server"
      ],
      "env": {
        "QUANTAROUTE_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. 保存并重启 Claude Desktop以应用更改。

适用于 Cursor

添加到 MCP 配置文件（~/.cursor/mcp.json）中：

{
  "mcpServers": {
    "quantaroute": {
      "command": "npx",
      "args": [
        "-y",
        "@quantaroute/mcp-server"
      ],
      "env": {
        "QUANTAROUTE_API_KEY": "your-api-key-here"
      }
    }
  }
}

更改后重启 Cursor。

环境变量

• QUANTAROUTE_API_KEY（必填）：你的 QuantaRoute API 密钥
  • 从此处获取 API 密钥：https://developers.quantaroute.com
  • 免费套餐测试密钥：demo_free_key_123（用于测试）

可用工具

geocode

对地址进行地理编码，获取 DigiPin 编码和坐标。

参数：

• address（必填）：要进行地理编码的地址
• city（可选）：城市名称
• state（可选）：州名称
• pincode（可选）：邮政编码
• country（可选）：国家名称（默认为印度）

示例：

{
  "address": "Rohra Address, New Town",
  "city": "New Town",
  "state": "West Bengal",
  "pincode": "700163"
}

reverse_geocode

对 DigiPin 编码进行反向地理编码，获取坐标和地址。

参数：

• digipin（必填）：DigiPin 编码（格式：XXX-XXX-XXXX）

coordinates_to_digipin

将纬度和经度转换为 DigiPin 编码。

参数：

• latitude（必填）：纬度（-90 至 90）
• longitude（必填）：经度（-180 至 180）

lookup_location_from_coordinates

🚀 革新性功能：根据坐标获取行政边界。

返回：邮政编码、州、分区、地点、地区、人口密度等信息。

参数：

• latitude（必填）：纬度坐标
• longitude（必填）：经度坐标

lookup_location_from_digipin

根据 DigiPin 编码获取行政边界。

参数：

• digipin（必填）：DigiPin 编码

batch_location_lookup

批量查询多个位置（最多 100 个）。

参数：

• locations（必填）：位置对象数组
  • 每个对象可包含 latitude + longitude，或 digipin

batch_geocode

在单个请求中对多个地址进行地理编码（最多 100 个）。

参数：

• addresses（必填）：地址对象数组

autocomplete

获取地址自动补全建议。

参数：

• query（必填）：搜索查询（至少 3 个字符）
• limit（可选）：建议数量上限（默认值：5，最大值：10）

find_nearby_boundaries [COMING SOON...]

查找指定半径范围内的附近邮政边界。

参数：

• latitude（必需）：中心纬度
• longitude（必需）：中心经度
• radius_km（可选）：搜索半径，单位为 km（默认值：5.0，最大值：100）
• limit（可选）：结果数量上限（默认值：10，最大值：50）

validate_digipin

验证 DigiPin 格式，并检查它是否对应真实位置。

参数：

• digipin（必需）：要验证的 DigiPin 代码

get_usage

获取 API 使用情况统计信息和配额信息。

get_location_statistics

获取 Location Lookup 服务的实时统计信息。

get_health

检查 API 健康状态。

REST API 封装

此项目包含 REST API 封装，可通过 HTTP 端点让移动和 Web 应用使用所有 MCP 工具。

功能

• ✅ RESTful API：将所有 MCP 工具作为 HTTP 端点提供
• ✅ 身份验证：通过请求头或环境变量使用 API 密钥
• ✅ CORS 支持：可供 Web 和移动应用使用
• ✅ 支持 Vercel：针对无服务器部署进行优化
• ✅ 错误处理：全面的错误处理和验证

快速开始

REST API 已部署，可通过以下地址使用：

基础 URL：https://mcp-gc.quantaroute.com/api

注意：mcp-gc 代表 MCP Geocoding。命名遵循以下约定：

• mcp-gc.quantaroute.com - Geocoding MCP Server（本项目）

使用 REST API

1. 获取 API 信息：

curl https://mcp-gc.quantaroute.com/api

2. 对地址进行地理编码：

curl -X POST https://mcp-gc.quantaroute.com/api/geocode \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "address": "Rohra Address, New Town",
    "city": "New Town",
    "state": "West Bengal",
    "pincode": "700163"
  }'

3. 健康检查：

curl -X GET https://mcp-gc.quantaroute.com/api/health \
  -H "x-api-key: your-api-key-here"

4. 查找附近边界：[NOT RELEASED, COMING SOON...]

curl -X POST https://mcp-gc.quantaroute.com/api/find-nearby-boundaries \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "latitude": 28.6139,
    "longitude": 77.2090,
    "radius_km": 5.0,
    "limit": 10
  }'

此端点可查找指定半径范围内的附近邮政边界。适用于：

• 查找某个位置 X km 范围内的所有邮政编码
• 查找附近的行政边界
• 基于位置的搜索和发现

JavaScript/TypeScript 示例

// Geocode an address
const response = await fetch('https://mcp-gc.quantaroute.com/api/geocode', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key-here'
  },
  body: JSON.stringify({
    address: 'Rohra Address, Action Area I',
    city: 'New Town',
    state: 'West Bengal'
  })
});

const data = await response.json();
console.log(data);

Python 示例

import requests

# Geocode an address
response = requests.post(
    'https://mcp-gc.quantaroute.com/api/geocode',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'your-api-key-here'
    },
    json={
        'address': 'Rohra Address, Action Area I, Ghuni',
        'city': 'New Town',
        'state': 'West Bengal'
    }
)

data = response.json()
print(data)

部署自己的实例

如果要部署自己的实例：

1. 部署到 Vercel：

   vercel
   

2. 设置环境变量（可选，用于测试）：

   vercel env add QUANTAROUTE_API_KEY
   

3. 配置自定义域名（可选）：

   • 在 Vercel 中添加自定义域名
   • 配置指向 Vercel 的 DNS CNAME 记录
   • 等待 DNS 传播和 SSL 证书签发

API 文档

完整的 REST API 文档请参阅 API.md。

可用端点：

• GET /api - API 信息
• GET /api/health - 健康检查
• GET /api/usage - 使用情况统计信息
• GET /api/location-statistics - 位置服务统计信息
• GET /api/autocomplete?q=query - 地址自动补全
• GET /api/validate-digipin?digipin=XXX-XXX-XXXX - 验证 DigiPin
• POST /api/geocode - 对地址进行地理编码
• POST /api/reverse-geocode - 对 DigiPin 进行反向地理编码
• POST /api/coordinates-to-digipin - 将坐标转换为 DigiPin
• POST /api/batch-geocode - 批量对地址进行地理编码
• POST /api/lookup-location-from-coordinates - 根据坐标查询位置
• POST /api/lookup-location-from-digipin - 根据 DigiPin 查询位置
• POST /api/batch-location-lookup - 批量查询位置
• POST /api/find-nearby-boundaries - 查找附近边界 [COMING SOON...]

身份验证

该 API 支持两种身份验证方式：

1. 请求标头（推荐用于生产环境）：

   x-api-key: your-api-key-here
   

   • 用户应从 developers.quantaroute.com 获取自己的 API 密钥
   • 每次请求都在 x-api-key 标头中发送 API 密钥
   • 后端 API 会验证每位用户的 API 密钥，并分别跟踪用量

2. 环境变量（测试时可选的备用方式）：

   QUANTAROUTE_API_KEY=your-api-key-here
   

   • 仅当未提供 x-api-key 标头时使用
   • 适用于测试和开发
   • 不建议用于生产环境

优先级：请求标头的优先级高于环境变量。

获取 API 密钥：

• 访问 developers.quantaroute.com
• 注册并获取 API 密钥
• 在所有 API 请求的 x-api-key 标头中使用该密钥

开发

先决条件

• Node.js 18+
• TypeScript 5+

设置

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

项目结构

mcp-server/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── client.ts         # QuantaRoute API client
├── api/
│   └── [...path].ts      # REST API wrapper (Vercel serverless function)
├── dist/                 # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
├── vercel.json           # Vercel configuration
├── README.md
└── API.md                # REST API documentation

API 文档

完整 API 文档：https://api.quantaroute.com/v1/digipin/docs

许可证

MIT 许可证

支持

• 网站：https://quantaroute.com
• API 文档：https://api.quantaroute.com/v1/digipin/docs
• 问题反馈：https://github.com/mapdevsaikat/quantaroute-geocoder/issues

支持的平台

✅ Claude Desktop - 完全支持
✅ Cursor - 完全支持
✅ 其他兼容 MCP 的客户端 - 应适用于任何兼容 MCP 的应用程序

AI 助手中的使用示例

配置完成后，AI 助手（Claude、Cursor AI 等）可以使用以下工具：

示例 1：地理编码

User: "What's the DigiPin for Biswa Bangla Gate, New Town?"

Assistant: [Uses geocode tool]
The DigiPin code for that address is 2TF-39M-JT5F, located at coordinates 22.5788545, 88.4716628.
Full Address: Biswa Bangla Gate, New Town, Biswa Bangla Sarani, Action Area I, New Town, Bidhannagar, North 24 Parganas, West Bengal, 700156, India

示例 2：地点查询

User: "What administrative boundaries are at coordinates 28.6139, 77.2090?"

Assistant: [Uses lookup_location_from_coordinates tool]
That location is in:
- Pincode: 110001
- State: Delhi
- Division: New Delhi Central
- Locality: Connaught Place
- District: New Delhi

示例 3：反向地理编码

User: "What's the address for DigiPin 2TF-3FT-J825?"

Assistant: [Uses reverse_geocode tool]
The DigiPin 2TF-3FT-J825 corresponds to:
- Address: FE Block, Sector III, Bidhannagar, North 24 Parganas, West Bengal, 700106, India
- Coordinates: 22.580587°N, 88.419001°E

故障排除

Claude Desktop 问题

1. Claude Desktop 中未显示服务：

   • 确认配置文件路径对你的操作系统正确无误
   • 检查 JSON 语法是否有效
   • 完全重启 Claude Desktop

2. “找不到命令”错误：

   • 确认已安装 Node.js 18+：node --version
   • 确认 npx 可用：which npx

3. API 身份验证错误：

   • 检查配置中的 QUANTAROUTE_API_KEY 是否设置正确
   • 在 https://api.quantaroute.com 确认 API 密钥有效

Cursor 问题

1. MCP 服务未加载：

   • 检查 ~/.cursor/mcp.json 是否存在且包含有效的 JSON
   • 完全重启 Cursor
   • 检查 Cursor 的 MCP 日志中是否有错误

2. 工具不可用：

   • 确认服务正在运行（检查 Cursor 的 MCP 状态）
   • 确认 API 密钥已正确配置