nominatim-mcp-server

---

概要

Nominatim と Overpass API を通じて OpenStreetMap データを利用できます。場所や住所をジオコーディングし、座標から最寄りの住所を特定し、既知の OSM オブジェクトを検索できます。また、地点の周囲、バウンディングボックス内、または OSM 境界内のフィーチャをタグでクエリできます。

ツール

ツール	説明
openstreetmap_search_places	場所名または住所を座標と構造化された場所データに変換します
openstreetmap_reverse_geocode	緯度／経度を最寄りの住所または場所名に変換します
openstreetmap_lookup_objects	ID を指定して、既知の OSM オブジェクトの住所レコードを取得します
openstreetmap_query_nearby	地点から指定半径内にある OSM フィーチャを検索します
openstreetmap_query_bbox	バウンディングボックス内、または都市、公園、地域などの OSM 境界内にある OSM フィーチャを検索します
openstreetmap_query_raw	他のツールでは表現できないクエリを実行するため、Overpass QL の生クエリを実行します

機能リファレンス

openstreetmap-guide スキルでは、場所の解決、空間クエリ、ページング、カバレッジとタグの結果の解釈について説明しています。

正規の検証の前に引数の別名を受け付けます。nearby クエリと reverse クエリでは lat / lon の代わりに latitude / longitude、nearby の radius_meters の代わりに radius_m、search の query の代わりに q を使用できます。どちらか一方の表記のみを指定し、両方は指定しないでください。radius、tag、tags は引き続き無効です。公開されるスキーマでは正規の名前を使用します。

openstreetmap_search_places _ツール

• 自由形式の query または構造化フィールド street、city、county、state、country、postalcode のいずれかを指定します。両方は指定できません。最大40件の結果を返します（limit のデフォルトは5。より大きな limit は40として処理され、limitNotice が返されます）。countrycodes、layer、featureType、および bounded: true で範囲を制限する viewbox によって絞り込めます。
• 結果には座標、構造化された address、boundingbox、importance、osm_type と osm_id が含まれます。extratags を指定すると、連絡先や物理的属性のタグが追加されます。最初のページが空の場合は no_results エラーになります。
• ページが満杯の場合、次の呼び出しで exclude_place_ids に渡す nextExcludeIds が返されます。結果がなくなると、エラーではなく、通知とともに0件の結果が返されます。

---

openstreetmap_reverse_geocode _ツール

• lat ／ lon と、3（国）から18（建物、デフォルト）までの zoom を指定します。layer のデフォルトは address,poi です。
• 構造化された address、osm_type と osm_id、boundingbox を含む、最も近いインデックス登録済みオブジェクトを返します。OSM データがない座標は no_coverage エラーになります。

---

openstreetmap_lookup_objects _ツール

• osm_ids は最大500件まで指定できます。各 ID の先頭には N、W、R のいずれかを付けます（["N240109189"]）。形式が不正な ID は invalid_id_format エラーになります。
• 最初の50件の一意な ID を検索し、残りは次の呼び出し用に deferred_ids として返します。
• 見つかったオブジェクトの住所レコードを返し、残りは not_found に列挙します（街灯など、Nominatim がインデックス登録していないオブジェクトも含まれます）。notice には、存在を確認するための openstreetmap_query_raw クエリが含まれます。

---

openstreetmap_query_nearby _ツール

• lat ／ lon と、最大50,000の radius_meters（デフォルトは1,000）を指定します。主タグは amenity または tag_key のいずれか1つで、任意で tag_value を指定できます。さらに、AND 条件で適用する filters を最大5つ指定できます。1ページあたり最大500件のフィーチャーを返します（より大きな limit は500として処理され、limitNotice が返されます）。
• デフォルトでは値を完全一致で照合します。list_item モード（tag_value_match、またはフィルターの match）では、セミコロン区切りリスト内の項目を照合するため、cuisine = pizza の場合、cuisine=pizza;italian も見つかります。
• OpenStreetMap で別のキーのタグとして登録されている amenity 値（amenity: "museum"。博物館は tourism=museum）を指定すると、再試行するキーを示す notice が返されます。
• フィーチャーには osm_type と osm_id、座標、distance_meters（フィーチャーの最近傍点までの距離）、すべてのタグが含まれます。近い順に並べられ、effectiveTag にはフィルターチェーンが反映されます。

---

openstreetmap_query_bbox _ツール

• 1回の呼び出しで指定できる範囲は1つです。south、west、north、east の角座標、またはジオコーディング結果の osm_type と osm_id から作成した R ／ W 境界参照（R237385）を指定します。タグフィルター、リスト項目の照合、該当する amenity の通知、1ページあたり最大500件の上限は openstreetmap_query_nearby と同じです。
• effectiveArea には within の解決方法が反映され、areasTimestamp にはエリアデータの経過時間が示されます。エリアに対応しない参照を指定すると、通知とともに空のページが返されます。
• west が east より大きい場合は、日付変更線をまたぐボックスです。south が north より大きい場合は invalid_bbox エラーになります。

---

openstreetmap_query_raw _ツール

• [out:json] を含む任意の Overpass QL を指定できます。timeout_seconds に基づく [timeout:N]（最大180、デフォルト30）が設定され、クエリに指定がない場合は [maxsize:268435456]（256 MiB）が追加されます。1ページあたり最大500要素を返します（より大きな limit は500として処理され、limitNotice が返されます）。
• 生の要素（ways には nodes[]、relations には members[] が含まれます）に加えて、total_elements と、送信された effectiveQuery を返します。形式が不正な QL は、Overpass の解析エラーを含む query_error になります。
• max_element_bytes（デフォルト20,000、最小1,000）を超える要素では、members、nodes、geometry 配列が省略され、withheld_keys に列挙されます。取得方法は withheldElements と withheldNotice に示されます。

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、切り替え可能な認証（none／jwt／oauth）、交換可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを備えています。

OpenStreetMap 固有の機能：

• Nominatim へのリクエスト間隔は 1,050 ms に設定され、1 秒あたり 1 リクエストというポリシーを順守します。OSM_USER_AGENT により、サーバーを両方の上流サービスに識別させます
• Overpass クエリは、エンドポイントごとに OSM_OVERPASS_MAX_CONCURRENCY で制限されます。また、OSM_OVERPASS_ENDPOINTS を使ったフェイルオーバーを任意で有効にできます（Overpass エンドポイントのフェイルオーバーを参照）
• Overpass ツールは limit と offset を使ったページ分割に対応し、totalFound、truncated、nextOffset を返します。結果は 10 分間（Nominatim は 60 分間）キャッシュされるため、ページを切り替えても上流への新たなリクエストは発生しません
• 64 MiB を超える Overpass レスポンスは result_too_large として失敗します
• OSM_NOMINATIM_BASE_URL と OSM_OVERPASS_BASE_URL を設定すると、サーバーの接続先をセルフホストまたはミラーのインスタンスにできます

エージェントに適した出力：

• effectiveQuery、effectiveTag、effectiveArea に送信内容が反映されます。Overpass のレスポンスには data_timestamp と servingEndpoint が追加され、すべてのレスポンスに ODbL の attribution が含まれます
• いずれかのツールから得た osm_type と osm_id を openstreetmap_lookup_objects に渡せます。また、ジオコーディングされた relation または way は、openstreetmap_query_bbox 用の within 参照になります
• Nominatim ツールはタグによる選択を行わず、tagSelectionCaveat でそのことを示します。正規表現、選択肢、否定を使う場合は openstreetmap_query_raw を使用します
• Markdown 出力では名前とタグ値がエスケープされます。structuredContent には未加工のテキストが保持されます

はじめに

インストールせずに、ホストされたインスタンスに接続します：

claude mcp add --transport http openstreetmap-mcp-server https://openstreetmap.caseyjhand.com/mcp

または、ローカルで実行します：

claude mcp add openstreetmap-mcp-server -- npx -y @cyanheads/openstreetmap-mcp-server

その他のクライアントでは、MCP 設定ファイルに以下を追加します：

{
  "mcpServers": {
    "openstreetmap-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/openstreetmap-mcp-server"]
    }
  }
}

API キーは不要です。大量に利用する場合は、OSM_NOMINATIM_BASE_URL と OSM_OVERPASS_BASE_URL を独自のインスタンスに設定してください。Docker またはソースからのビルドについては、サーバーの実行を参照してください。

設定

変数	説明	デフォルト
OSM_NOMINATIM_BASE_URL	Nominatim のベース URL。https://maps.example.com/nominatim のようなパスプレフィックスに対応しています。	https://nominatim.openstreetmap.org
OSM_OVERPASS_BASE_URL	すべてのクエリを 1 つの Overpass エンドポイントに固定し、フェイルオーバーを無効にします。	未設定
OSM_OVERPASS_ENDPOINTS	順序付きの Overpass エンドポイントをカンマ区切りで指定します。複数指定するとフェイルオーバーが有効になります。OSM_OVERPASS_BASE_URL が設定されている場合は無視されます。	https://overpass-api.de/api/interpreter
OSM_OVERPASS_MAX_CONCURRENCY	エンドポイントごとの Overpass 同時実行クエリの最大数。パブリックインスタンスでは、ユーザーごとに 1 つまでです。	1
OSM_USER_AGENT	Nominatim と Overpass に送信する User-Agent。利用ポリシーにより必須です。	openstreetmap-mcp-server/<package version>
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。サーバーはコード内で stateless を宣言しており、明示的に指定した値が優先されます。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

オプションで上書き可能な設定の全一覧は .env.example を参照してください。いずれかの OSM_* 変数に無効な値が設定されている場合、該当する変数名を示すメッセージとともにサーバーの起動が停止します。

Overpass エンドポイントのフェイルオーバー

デフォルトでは、すべての Overpass クエリは、FOSSGIS が運営するメインインスタンスという1つのエンドポイントに送信されます。OSM_OVERPASS_ENDPOINTS にほかのエンドポイントを追加すると、呼び出しに失敗した際、記載順に次のエンドポイントへ切り替わります。

OSM_OVERPASS_ENDPOINTS="https://overpass-api.de/api/interpreter,https://overpass.private.coffee/api/interpreter"

• 繰り返し失敗するエンドポイントは、一定時間（30秒から始まり、最大10分まで倍増）スキップされます
• すべてのエンドポイントが失敗すると、呼び出しは rate_limited、upstream_error、overpass_unavailable、endpoints_rejected、endpoints_exhausted、または endpoints_unavailable で失敗し、メッセージには各エンドポイントの結果が含まれます
• エンドポイントはオリジンのみ（https://overpass-api.de）で、servingEndpoint、エラーメッセージ、ログに報告されます
• 追加したエントリーはフェイルオーバー専用であり、並列実行数は増加しません。並列クエリを許可しているインスタンスでは、エントリーに |N を追加すると N 個のスロットを指定できます（https://mirror.example/api/interpreter|4）。URL 内のリテラルの | は %7C と記述してください。公開されている FOSSGIS サーバーの並列数は指定しないでください
• スロット待ちの呼び出しは、30秒間順番待ちした後、30秒以上の retryAfter とともに pacer_shed で失敗します

エンドポイントを追加すると、クエリが第三者に送信されます。OSM wiki のインスタンス一覧で利用ポリシーを確認し、世界全域のデータを保持していることを確かめてください（地域限定のインスタンスは、抽出範囲外のクエリに対して空の HTTP 200 を返します）。また、ミラーはメインインスタンスよりデータの反映が遅れることがあります。servingEndpoint と data_timestamp で、応答したホストとデータの新しさを確認できます。

サーバーの実行

ローカル開発

Bun v1.4.0 以上（または Node.js v24 以降）が必要です。

git clone https://github.com/cyanheads/openstreetmap-mcp-server.git
cd openstreetmap-mcp-server && bun install
cp .env.example .env
# edit .env to override endpoints or the User-Agent as needed

• 本番バージョンをビルドして実行する：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio
  

• チェックとテストを実行する：

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/openstreetmap-mcp-server:latest

# or build locally
docker build -t openstreetmap-mcp-server .
docker run --rm -p 3010:3010 openstreetmap-mcp-server

このイメージはステートレスセッションモードで http://localhost:3010/mcp の HTTP サービスを提供し、/var/log/openstreetmap-mcp-server にログを記録します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。省略するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。実行時のテレメトリーは、-e OTEL_ENABLED=true を渡すまで無効です。

プロジェクト構成

ディレクトリ	用途
src/mcp-server/tools	ツール定義（*.tool.ts）と、入力、フォーマット、エスケープの共通ヘルパー。Nominatim と Overpass のツールが6つあります。
src/services/nominatim	Nominatim サービス：検索、逆ジオコーディング、ルックアップ用のレート制御付き API クライアントと、エラー解析。
src/services/overpass	Overpass サービス：クエリビルダー、エンドポイントのフェイルオーバーと実行、要素の正規化、エラー解析。
src/config	サーバー固有の環境変数の解析と、Zod による検証。
tests/	ツール、サービス、セキュリティに関する単体テストと統合テスト。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックでは try/catch を使用しないでください
• ログには ctx.log、ストレージには ctx.state を使用します
• 新しいツールは src/index.ts の createApp() 配列に登録します
• 外部 API 呼び出しは、未加工データの検証 → ドメイン型への正規化 → 出力スキーマの返却、の順にラップします。不足しているフィールドを捏造しないでください

貢献

Issue の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。

OpenStreetMap の貢献者による地図データは、Open Database License（ODbL） の下で利用できます。