OpenCage Geocoding MCP Server

OpenCage Geocoding MCP Server

OpenCage ジオコーディング APIを使用して、ジオコーディング機能を提供する MCP（Model Context Protocol）サーバーです。 このサーバーを使用すると、住所と地理座標を相互に変換できます。

**ご注意ください：**ここに示す例は、claude.ai のデスクトップクライアントとの統合に基づいています。MCP という概念はほかのサービスでもサポートされていますが、設定が多少異なる場合があります。

機能

• フォワードジオコーディング：住所や地名を座標（緯度／経度）に変換します
• リバースジオコーディング：座標を住所に変換します
• API ステータスの監視：API の使用状況とレート制限を確認します（penCage アカウントに厳格な上限が設定されている場合）。

前提条件

1. Node.js（バージョン 20 以降）
2. OpenCage ジオコーディング API キー：OpenCage のウェブサイトに登録して、無料トライアルのジオコーディング API キーを取得します

インストール

0. MCP は適切なツールですか？

   この MCP は、たとえば LLM に手動でプロンプトを入力する場合など、少量のジオコーディングに適しています。

   ただし、住所や座標が多数含まれる CSV ファイルや、データが大量に保存されたデータベースへの接続など、大量のデータを処理する場合は、コマンドラインツールを使用するか、LLM に API を直接呼び出すスクリプトを作成させるほうが、ほぼ確実に高速で低コストです。

   ジオコーディング API を利用する際のベストプラクティスを AI に学習させるための、Markdown 形式の opencage-geocoding-api SKILL ファイルを提供しています。

1. リポジトリをクローンします。リポジトリのディレクトリに移動します

git clone [email protected]:OpenCageData/opencage-geocoding-mcp.git
# or
git clone https://github.com/OpenCageData/opencage-geocoding-mcp.git

cd opencage-geocoding-mcp

2. 依存関係をインストールします：

npm install

これだけで、MCP を Claude Desktop で使用できるようになります（下記参照）。

MCP を開発し、コマンドラインから MCP にクエリを送信する場合は、さらに以下が必要です。

3. OpenCage ジオコーディング API キーを環境変数として設定します：

export OPENCAGE_API_KEY="your_opencage_geocoding_api_key_here"

4. プロジェクトをビルドします：

npm run build

使い方

Claude Desktop 内での使用

この設定を Claude Desktop の設定ファイルに追加します。

Mac では、設定ファイルは（~/Library/Application Support/Claude/claude_desktop_config.json）にありますが、メニューからファイルを開くこともできます：Settings > Developer > Edit Config

{
  "mcpServers": {
    "opencage-geocoding": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/opencage-geocoding-mcp/build/index.js"],
      "env": {
        "OPENCAGE_API_KEY": "your_opencage_geocoding_api_key_here"
      }
    }
  }
}

利用可能なツール

注：コマンドを初めて実行するときは、Claude に許可を与える必要があります。

1. geocode-forward

住所や地名を座標とその場所に関する情報に変換します。

パラメーター：

• query（必須）：ジオコーディングする住所または地名
• countrycode（任意）：国を指定します（ISO 3166-1 alpha-2 コード）
• bounds（任意）：境界ボックス（min_lon,min_lat,max_lon,max_lat）
• language（任意）：結果の言語（例：'en'、'de'、'fr'）
• limit（任意）：結果の最大数（1～100、デフォルトは 10）
• no_annotations（任意）：位置情報の注釈を除外します

プロンプトの例

Prompt: "What are the coordinates of Trafalgar Square, London?"
Result: coordinates, timezone, local currency, etc

Prompt: "Where is Les Vans, France? Which Department is it in?"
Result: coordinates, and correct answer that Les Vans is in the Ardèche department

Prompt: "In welchem Bundesland liegt Weimar?"
Result: coordinates, and correct answer that Weimar is in Thüringen

2. geocode-reverse

座標を住所とその場所に関する情報に変換します。

パラメーター：

• latitude（必須）：十進形式の緯度座標（-90～90）
• longitude（必須）：十進形式の経度座標（-180～180）
• language（任意）：結果の言語
• no_annotations（任意）：位置情報の注釈を除外します

プロンプトの例

Prompt: "what is the address at 38.8976, -77.0365?"
Result: "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States of America"

Prompt: "Which province are the coordinates 41.38700, 2.16995 in?"
Result: "Coordinates are in Barcelona in the province of Catalonia"

3. get-opencage-info

現在の API 使用状況とレート制限を確認します。 **注：**サブスクリプションをご利用のお客様には、使用量の厳格な上限はありません。関連ドキュメントをご覧ください。

**パラメーター：**なし

**戻り値：**残りのリクエスト数、レート制限、リセット時刻に関する情報。

利用可能なプロンプト

geocoding-assistant

ジオコーディングタスクを支援するアシスタントです。ジオコーディングツールの効果的な使い方を案内します。

エラー処理

サーバーには、包括的なエラー処理が含まれています。

• 無効な API キー
• レート制限超過
• ネットワークエラー
• 無効な座標または住所
• API サービスが利用できない

環境変数

• OPENCAGE_API_KEY：OpenCage のジオコーディング API キー（必須）

トラブルシューティング

1. 「API key required」エラー：環境変数 OPENCAGE_API_KEY が設定されていることを確認してください
2. 「No results found」：より具体的な住所、または異なる形式の住所を試してください。OpenCage のクエリ形式に関するガイドを参照してください
3. レート制限エラー：get-api-status ツールで API の使用状況を確認してください
4. ネットワークエラー：インターネット接続またはOpenCage の公開ステータスページを確認してください

関連リンク

• OpenCage のホームページ - ジオコーディング API キーを取得できます

• OpenCage API ドキュメント - OpenCage ジオコーディング API の完全なリファレンス

• OpenCage MCP チュートリアル

• Model Context Protocol - MCP について詳しく知る

OpenCage GmbH とは？

私たちは、オープンデータを基盤とする世界規模のジオコーディング APIとジオサーチサービスを運営しています。 私たちについて詳しくはこちらをご覧ください。

また、位置情報ベースのサービスを開発する人々のための定期的なミートアップシリーズ、Geomobも開催しています。地理空間分野のイノベーションをできる限り取り上げています。地理空間に関心がある方なら、Geomob ポッドキャストもきっとお楽しみいただけるでしょう。