quantaroute-geocoder

QuantaRoute MCP Server

QuantaRoute Geocoding API を使用して、強力なジオコーディング、場所の検索、DigiPin 処理機能を AI アシスタント（Claude Desktop、Cursor など）に提供する Model Context Protocol（MCP）サーバーです。

パッケージ：@quantaroute/mcp-server（AI エージェント向け MCP サーバー）
SDK：quantaroute-geocoding（Node.js/TypeScript SDK）

✅ Claude Desktop および Cursor と完全に互換性があります

機能

🗺️ ジオコーディングツール

• 住所をジオコードして、DigiPin コードと座標を取得
• DigiPin コードをリバースジオコードして、住所を取得
• 座標を変換して、DigiPin コードを取得
• DigiPin の形式と位置を検証
• 複数の住所を一括でジオコード（最大 100 件）
• 住所の候補をオートコンプリート

🚀 Nominatim + Pincode + Digipin による画期的な場所検索

• 座標から行政区域の境界を検索（pincode、州、division、地域）
• DigiPin コードから検索
• 複数の場所を一括検索
• 半径内の近隣境界を検索［近日公開…］
• インド全土の36,000 件以上の郵便区域境界にアクセス

📊 ユーティリティツール

• API の使用統計を取得
• 場所の統計情報（境界、州、division）を取得
• 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

🚀 画期的な機能：座標から行政区域の境界を取得します。

返される情報：pincode、州、division、地域、地区、人口密度など。

パラメーター：

• latitude（必須）：緯度座標
• longitude（必須）：経度座標

lookup_location_from_digipin

DigiPin コードから行政区域の境界を取得します。

パラメーター：

• digipin（必須）：DigiPin コード

batch_location_lookup

複数の場所を一括検索します（最大 100 件）。

パラメーター：

• locations（必須）：場所オブジェクトの配列
  • 各オブジェクトには latitude + longitude または digipin を指定できます

batch_geocode

1 回のリクエストで複数の住所をジオコードします（最大 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 ラッパー

このプロジェクトには、すべての MCP ツールを HTTP エンドポイント経由でモバイルアプリやウェブアプリから利用できるようにする REST API ラッパーが含まれています。

機能

• ✅ RESTful API：すべての MCP ツールを HTTP エンドポイントとして公開
• ✅ 認証：ヘッダーまたは環境変数による API キー認証
• ✅ CORS 対応：ウェブアプリやモバイルアプリですぐに利用可能
• ✅ Vercel 対応：サーバーレスデプロイ向けに最適化
• ✅ エラー処理：包括的なエラー処理と検証

クイックスタート

REST API はすでにデプロイ済みで、次の URL ですぐに利用できます。

ベース 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 - Location サービスの統計情報
• 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 は次の 2 つの方法で認証できます。

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 License

サポート

• ウェブサイト：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 にサーバーが表示されない場合：

   • OS に対応した設定ファイルのパスが正しいことを確認します
   • JSON 構文が正しいことを確認します
   • Claude Desktop を完全に再起動します

2. 「Command not found」エラーが表示される場合：

   • 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 キーが正しく設定されていることを確認します