elevation-mcp-server

---

概要

USGS 3DEP（米国内では 1～30 m）および世界各地をカバーする Open Topo Data を利用して、地球上のあらゆる場所の標高と地形を分析できます。地点の標高を検索したり、ルートの登り・下りや勾配を測定したり、エリア内の最高点と最低点を見つけたり、地形が見通しを遮るかどうかを確認したりできます。API キーは不要です。

ツール

ツール	説明
elevation_get_points	1～100 個の座標地点の地表標高をメートルとフィートで取得します。各値のデータセットと解像度も返します
elevation_get_profile	等間隔の地点でルートをサンプリングし、距離、累積上昇量、累積下降量、標高範囲、最急勾配を要約します
elevation_get_grid	バウンディングボックス上のノードグリッドをサンプリングし、最高点、最低点、平均標高、起伏を報告します
elevation_check_line_of_sight	地球の曲率と屈折を考慮して、2 地点間の見通しを地形が遮るかどうかを判定します。無線リンクでは第 1 フレネルゾーンのクリアランスも確認します

機能リファレンス

成功した結果には、両方の応答サーフェスに vertical_reference が含まれます。公開 SRTM は EGM96 を使用します。米国本土の 3DEP では通常 NAVD88 ですが、返されるラスターの基準は未検証であり、他の地域では異なる場合があります。Mapzen およびセルフホストの Open Topo Data の基準は不明、または変動します。データなしの結果からは標高基準を特定できません。標高は変換せずに返されるため、異なるデータセット間で共通の基準面に正規化されることはありません。water_surface_m を使用するには、互換性のある地形基準が必要です。値がゼロであることや、source: opentopodata であることだけでは、互換性は確認できません。

elevation_get_points _ツール

• points：10進度（WGS84）の {lat, lon} オブジェクトを1～1,000個、または単一のポイントで指定します。検証とサンプリングの対象は先頭の100個のみで、それ以降は検証されません
• requested_points、processed_points、remaining_points は、重複やデータなしのポイントも含め、送信された位置の数を示します。next_offset はこの呼び出しで処理した先頭部分の次のインデックスです。すべて処理済みの場合は null です。続行するには、originalPoints.slice(next_offset) を使用します。ここでの originalPoints は、その呼び出しで送信した配列です。次のスライスには、その都度新たに送信した配列を使用してください
• 各ポイントは ok または no_data として返されます（データなしでも呼び出しは失敗しません）。結果には elevation_m ／ elevation_ft、dataset、resolution_m（mapzen では省略）が含まれます。3DEP の応答には raster_id と acquisition_date も含まれます。points_with_data はデータのあるポイントの数を示します

---

elevation_get_profile _ツール

• path：移動順に並べた頂点を2～1,000個指定します（連続する重複は削除されます）。samples：経路上に等間隔で配置するポイントの数を2～250個指定します。両端点を含みます（デフォルトは100）
• summary には total_distance_m、ascent_m ／ descent_m（フィート単位も含む）、始点、終点、最低標高、最高標高、highest_point ／ lowest_point、および発生位置を示す max_grade_pct ／ min_grade_pct が含まれます。上昇量は報告される sample_interval_m によって異なります。degenerate_path（経路の長さが1 m未満）、antipodal_path（特定された0始まりの入力頂点の間に中間ウェイポイントを追加してください）、または no_coverage（データのあるサンプルがない）の場合は失敗します
• include_samples（デフォルトは true）を指定すると、サンプルごとの距離、位置、標高、勾配、データセット、解像度を含む samples[] が返されます。false を指定すると、これとサンプルテーブルが省略されます。それ以外の結果は変わりません

---

elevation_get_grid _ツール

• south、west、north、east：10進度で境界を指定します（ボックスは経度180度をまたげません）。rows と cols はそれぞれ2～25（デフォルトは10）で、rows × cols は最大250です
• elevations_m と cell_datasets は [row][col] でインデックス指定する行列です（行0は北、列0は西、データがない場合は null）。これに加えて、summary.highest、summary.lowest、mean_elevation_m、relief_m が返されます。invalid_bbox、too_many_cells、または no_coverage の場合は失敗します
• ノードは境界を含むポイントサンプルであり、セルの平均値ではありません

---

elevation_check_line_of_sight _ツール

• observer と target のポイントは、互いに1,000 km以内で指定します。observer_height_m（デフォルトは1.7）と target_height_m（デフォルトは0）は、それぞれ地上高0～10,000 mです。earth_model は flat、geometric、optical（デフォルト、κ 0.13）、または radio（κ 0.25）を指定します。samples は3～250（デフォルトは100）です。任意で water_surface_m（-500～9,000）と frequency_mhz（30～300,000）を指定できます
• verdict は clear、blocked、または indeterminate です（データのないサンプルがあると、見通しは未確認のままになります）。min_clearance_m ／ min_clearance_ft、limiting_point、および遮られている場合は first_obstruction も返されます。same_endpoints（両端点の距離が1 m未満）、sightline_too_long（両端点の距離が1,000 km超）、または endpoint_no_data の場合は失敗します
• frequency_mhz を指定すると fresnel が追加されます。これは、第1フレネルゾーンの自由空間における60％の基準に対する判定で、sufficient、insufficient、または indeterminate が返されます。min_clearance_ratio（ゾーン半径に対するクリアランスの比率）と、それを制限するサンプルも返されます。このサンプルは limiting_point と異なることがよくあります
• 地形のみが対象です。建物や植生が考慮されるのは、標高データソースに含まれている範囲に限られます。Mapzen が海底の深さを報告する場合、クリアランスは海面までの距離として測定されます。USGS 3DEP の0 m未満の値（一部の湾の海底、または陸地）は、water_surface_m で水位を指定しない限り、受信値として扱われます。水位を指定すると、すべてのサンプルに適用されます

---

すべてのツールで共通の失敗

理由	コード	発生条件
usgs_unavailable	ServiceUnavailable	USGS 3DEP が応答しなかったか、リクエストを拒否しました。再試行が有効かどうかは data.retryable で示されます
opentopodata_unavailable	ServiceUnavailable	Open Topo Data が応答しなかったか、リクエストを拒否したか、利用できない応答を返しました。data.retryable については上記と同じです
opentopodata_rate_limited	RateLimited	Open Topo Data が HTTP 429 を返し続けたか、8 秒を超える待機を求めました。待機時間が最大 1 日以内の場合、秒単位の値が data.retryAfter に入ります
opentopodata_daily_limit	RateLimited	パブリックインスタンスのみ：このサーバーは直近 24 時間にすでに 1,000 件のリクエストを送信しているため、リクエストは送信されませんでした。枠が空くまでの秒数が data.retryAfter に入ります
opentopodata_config_rejected	ConfigurationError	OPENTOPODATA_BASE_URL のインスタンスが 401、403、404 を返した、リダイレクトした（セルフホストの場合のみ。リダイレクトは追跡しません）、srtm30m または mapzen がない、場所の上限が 100 未満、またはこのサーバーがリクエストしていないデータセットから応答した場合です。運用者による修正が必要です
sampling_deadline_exceeded	Timeout	45 秒のサンプリング時間を超えました（待機していたプロバイダーは data.provider に示されます）。または、ほかの呼び出しによる USGS 3DEP 検索のキュー待ちで、この呼び出しに時間が残らず、リクエストが送信されませんでした。その検索が完了するまでの秒数が data.retryAfter に入ります

カバレッジ範囲外はエラーではありません。その地点にデータがないことを示します。プロバイダーで障害が発生した場合、部分的な結果は返さず、呼び出し全体が失敗します。

機能

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

標高に関する機能：

• すべてのツールで source を指定できます。auto（デフォルト）では、USGS 3DEP のカバレッジ範囲内は USGS 3DEP に問い合わせ、3DEP のカバレッジ範囲外の地点とそれ以外のすべての地点は Open Topo Data に送信します。usgs_3dep と opentopodata はプロバイダーを固定します。フォールバックするのはカバレッジ範囲外の場合のみで、障害時にはフォールバックしません
• Open Topo Data は SRTM GL1 v3（約 30 m、北緯 60°から南緯 56°の陸地）のデータを返し、SRTM にタイルがない場所（高緯度地域、南極大陸、海底地形）では Mapzen の地形タイルを使用します
• 呼び出しごとの上限は、45 秒のサンプリング時間内で、地点 100 件、サンプル 250 件、またはグリッドセル 250 件です。3DEP では地点ごとに個別のリクエストを送信し（同時実行 6 件、1 秒あたり 10 件）、Open Topo Data では 1 リクエストにつき 100 地点を処理します
• パブリック Open Topo Data インスタンスは公開済みの制限を超えないよう、同時に 1 件のみリクエストを処理し、リクエストの開始間隔を 1.1 秒以上空け、サーバープロセスごとに直近 24 時間のリクエスト数を最大 1,000 件に抑えます
• プロファイル、グリッド、見通し線は、地点サンプルからローカルで計算します。大圏距離とリサンプリングを使用し、標準的な屈折を考慮した地球の曲率を適用します

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

• すべての値に出典情報を付与します。各地点、プロファイルのサンプル、グリッドセル、見通し線上の地点には dataset（usgs_3dep、srtm30m、mapzen）を記載します。Mapzen 以外では resolution_m も記載し（プロファイルとグリッドでは resolution_m_range）、計算結果には datasets_used の件数を追加します。また、データを返したすべてのデータセットを明記する Sources: 行を出力します
• データがない値は欠損値のままにします。地点またはサンプルにデータがない場合は標高を省略し、グリッドセルは 0 ではなく null とします。概要には、データがある値の数を示します
• 解釈に影響する事項を通知します。3DEP と Open Topo Data のデータが混在している場合、0 m 未満の Mapzen の値（海底の深さ）、見通し線上で 0 m 未満の 3DEP の値、サンプル間隔がデータソースより粗いまたは細かい場合、クリアランスの余裕が小さい場合、フレネルゾーンのクリアランスが 60% 未満でも無線経路が明瞭な場合などです

はじめに

公開ホストインスタンス

https://elevation.caseyjhand.com/mcp で公開インスタンスを利用できます。インストールは不要です。Streamable HTTP を介して、任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "elevation-mcp-server": {
      "type": "streamable-http",
      "url": "https://elevation.caseyjhand.com/mcp"
    }
  }
}

ホストインスタンスを呼び出すすべてのユーザーで、Open Topo Data の 1 日あたり 1,000 リクエストの利用枠を共有します。デフォルトの auto ソースでは、USGS 3DEP がデータを返さない地点に利用枠が使われます。3DEP は米国とその領土に加え、カナダとメキシコの広範囲をカバーしています。継続的に利用する場合は、ご自身のインスタンスを実行してください。

セルフホスト／ローカル

MCP クライアントの設定ファイルに以下を追加してください。

{
  "mcpServers": {
    "elevation-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/elevation-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "elevation-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/elevation-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使用します。

{
  "mcpServers": {
    "elevation-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/elevation-mcp-server:latest"]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• API キーは不要です。USGS 3DEP と Open Topo Data はどちらも API キーなしで利用できます。
• オプション：高負荷の利用またはホスト環境での利用向けに、srtm30m および mapzen データセットを備えたセルフホストの Open Topo Data インスタンス（設定を参照）。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/elevation-mcp-server.git

2. ディレクトリに移動します：

cd elevation-mcp-server

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

bun install

4. 環境を設定します：

cp .env.example .env
# optionally set OPENTOPODATA_BASE_URL to a self-hosted Open Topo Data instance

設定

変数	説明	デフォルト
OPENTOPODATA_BASE_URL	USGS 3DEP のカバー範囲外で使用する Open Topo Data インスタンスを指定する http または https URL。未設定または空白の場合は公開インスタンスを使用します。それ以外の URL はセルフホストインスタンスとして扱われます。	https://api.opentopodata.org
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。.env.example と Docker イメージでは stateless に設定されています。	auto
MCP_AUTH_MODE	認証：none、jwt、または oauth。jwt または oauth の場合、各ツールには tool:<tool_name>:read スコープが必要です。	none
MCP_LOG_LEVEL	ログレベル（debug、info、warning、error など）。	info
LOGS_DIR	ログファイル用ディレクトリ（Node.js のみ）。	<app-root>/logs
OTEL_ENABLED	OpenTelemetry を有効にします。	false

公開インスタンス以外の OPENTOPODATA_BASE_URL は、すべてセルフホストとして扱われます（Open Topo Data は MIT ライセンスで、Docker 上で実行できます）。同時リクエストは 4 件で、レート制限の時間枠はありません。srtm30m と mapzen という名前のデータセットを提供し、リクエストごとに少なくとも 100 地点を受け付ける必要があります。そうでない場合、呼び出しは opentopodata_config_rejected で失敗します。

すべてのサーバー設定と一般的なフレームワークのオーバーライドについては、.env.example を参照してください。

既知の制限

• Open Topo Data の公開制限。 公開インスタンスでは、1 リクエストあたり 100 地点、1 秒あたり 1 リクエスト、IP アドレスごとに 1 日あたり 1,000 リクエストが許可されています。各サーバープロセスはこの制限を下回るペースでリクエストを送りますが、カウントはプロセスごとで、再起動時にリセットされます。同じマシン上の複数のプロセス（クライアントセッションごとの stdio サーバー）や、同じアドレスを使う他のクライアントも上流のカウントを消費するため、上流が先にリクエストを拒否する場合があります（opentopodata_rate_limited）。
• 共有デプロイ。 多数のユーザーにサービスを提供するデプロイでは、すべてのリクエストが 1 つのアドレスから送信されるため、公開インスタンスでは 1 日あたり 1,000 回の枠を共有します。これは、地点検索で約 1,000 回、またはサンプル数 250 の呼び出しを 333 回分に相当します。リトライでもリクエストを消費する場合は、111 回まで減ることがあります。枠を使い切ると、auto で 3DEP の欠損が 1 つあるだけの呼び出しも含め、Open Topo Data を必要とするすべての呼び出しが最大 24 時間 opentopodata_daily_limit で失敗します。そのため、このようなデプロイでのグローバルな結果はベストエフォートです。OPENTOPODATA_BASE_URL を srtm30m と mapzen を読み込んだ独自のインスタンスに向ければ、上限を回避できます。サーバーには呼び出し元を識別して割り当てを制限する手段がないため、ある呼び出し元による大量の呼び出しは USGS 3DEP の処理を遅らせ、全員分のその日の公開枠を消費する可能性があります。
• グローバルな解像度。 SRTM は 30 m のレーダー表面モデルです。Mapzen の 1 秒角グリッドは、場所によってはより粗いデータソース（高緯度の一部では 7.5 秒角の GMTED2010、外洋では約 1.8 km の ETOPO1）から補間されています。3DEP のカバー範囲外では、プロファイルの累積標高差は過小評価され、視線解析ではデータソースの実際の解像度より狭い地形を見落とします。
• 整数メートル値。 Open Topo Data のデータセットは整数ラスターであり、上流では補間結果を最も近いメートルに丸めるため、緩やかな地形での累積標高差には 1 m の量子化ステップが含まれます。
• 水域。 SRTM は、陸地タイル内の水域を 0 m として報告します。SRTM のタイル範囲外では、Mapzen は海底深度を報告し、地点、プロファイル、グリッドにその値が含まれます。3DEP の水域上の値は、ラスターに応じて、水域調整済みの地表面、海面、または水深を表します。視線解析では、Mapzen の 0 未満の値に対しては 0 m までのクリアランスを測定しますが、USGS の応答からは湾の海底と海面下の陸地を区別できないため、3DEP の 0 m 未満の値は受信したまま使用します。通知ではこれらの値を示し、water_surface_m は水上の線から水面までを測定します。
• 混在するモデル。 3DEP は裸地の DEM で、米国本土では通常 NAVD88 が基準ですが、返されるラスターの正確な基準は未検証で、他の地域では異なる場合があります。公開 SRTM は EGM96 を使用するレーダー表面モデルで、樹冠や建物を部分的に含みます。Mapzen は地域ごとのデータソースを組み合わせています。セルフホスト可能なデータセット名からは基準を確認できません。標高は共通の基準面に変換されておらず、プロバイダー間の差は基準面だけでは説明できません。
• サンプリング。 サンプル間隔より狭い地形要素は見落とされます。たとえば、視線サンプル間の尾根、グリッドノード間の山頂（精度を高めるには summary.highest を中心に小さい範囲でグリッドを再取得します）、プロファイルサンプル間の短い登りなどです。間隔は常に報告されます。
• USGS 3DEP の処理能力。 地点クエリサービスには公表された上限もバッチエンドポイントもありません。このサーバーのペースでは毎秒約 10 地点となるため、サンプル数の上限は 250、予算は 45 秒です。検索によってキューが実行中の呼び出しの予算を超える場合、その呼び出しは直ちに sampling_deadline_exceeded と data.retryAfter を返して拒否されます。そのため、サンプル数 250 の呼び出しを 2 つ同時に行うと、順番に実行されます。2 つ目は約 25 秒後に再試行できます。
• USGS の取得日は M/D/YYYY 形式の生データのまま渡され、月や日にゼロが含まれることがあります。それ以外の形式は省略されます。
• 日付変更線。 グリッドボックスは経度 180 をまたげないため、2 つの呼び出しに分割してください。日付変更線をまたぐ経路や視線は使用できます。
• 視線解析の上限は 1,000 km です。この距離では、放物線による曲率近似によって中点の上昇量が最大約 10 m 過大評価されます。フレネルゾーンのチェックでは、選択した地球モデルで第 1 ゾーンを 60％の基準と照合しますが、サンプル位置のみを対象とし、回折損失や最悪ケースの k 係数は考慮しません。

サーバーの実行

ローカル開発

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

  # 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
  

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。4 つのツールを登録し、設定からサーバーの指示を構築して、標高サービスを起動および破棄します。
src/config	Zod による OPENTOPODATA_BASE_URL の解析と検証を行います。
src/mcp-server/tools/definitions	ツール定義（*.tool.ts）です。
src/mcp-server/tools/shared	4 つのツールで共有される入力スキーマ、出力スキーマ、および format() ヘルパーです。
src/services/elevation	ElevationSampler（ルーティング、3DEP のカバレッジ範囲、呼び出しごとの予算）、ジオメトリ、帰属表示、および単位ヘルパーです。
src/services/usgs-epqs	USGS Elevation Point Query Service クライアントです。
src/services/opentopodata	Open Topo Data クライアントとそのリクエストペーサーです。
src/services/shared	両方のクライアントで共有される、タイムアウト付きのフェッチ試行と制限付きの本文読み取りです。
docs/design.md	設計：ツールのコントラクト、計算、サービス、決定事項、および制限事項です。
tests/	モックされたアップストリームを使った単体テストとツールテストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジック内で try/catch を使用しないでください
• ロギングには ctx.log を、ストレージには ctx.state を使用してください
• 新しいツールは src/mcp-server/tools/definitions/index.ts の allToolDefinitions に登録してください
• 外部 API 呼び出しをラップします：生データを検証 → ドメイン型に正規化 → 出力スキーマを返す。不足しているフィールドを捏造してはいけません

データソースと帰属表示

データセット	dataset ID	提供元	利用条件
USGS 3D Elevation Program (3DEP)	usgs_3dep	USGS Elevation Point Query Service	パブリックドメイン（米国連邦政府の著作物）。米国地質調査所の 3D Elevation Program をクレジット表記してください。
SRTM GL1 v3	srtm30m	Open Topo Data	パブリックドメイン（NASA/USGS）。
Mapzen terrain tiles v1.1	mapzen	Open Topo Data	以下の複数ソースの帰属表示が必要です。

成功したすべての結果の Sources: 行には、回答に使用された各データセットがクレジット表記されます。また、Mapzen の値を使用したレスポンスには、Mapzen の完全な帰属表示が含まれます。公開されている Open Topo Data のインスタンスは、利用制限以外の利用条件を公開していません。そのサーバーソフトウェアは MIT ライセンスで、セルフホスト可能です。

Mapzen terrain tiles の帰属表示（tilezen/joerd の帰属表示ドキュメントからの原文）：

• ArcticDEM の地形データ DEM は DigitalGlobe, Inc. の画像から作成され、National Science Foundation の助成金 1043681、1559691、および 1542736 による資金提供を受けています；
• Australia の地形データ © Commonwealth of Australia (Geoscience Australia) 2017；
• Austria の地形データ © offene Daten Österreichs – Digitales Geländemodell (DGM) Österreich；
• Canada の地形データには、Open Government Licence – Canada に基づいてライセンスされた情報が含まれています；
• Europe の地形データは、欧州連合が資金提供した Copernicus のデータと情報を使用して作成されています - EU-DEM レイヤー；
• Global ETOPO1 の地形データ：U.S. National Oceanic and Atmospheric Administration
• Mexico の地形データの出典：INEGI, Continental relief, 2016；
• New Zealand の地形データ Copyright 2011 Crown copyright (c) Land Information New Zealand and the New Zealand Government (All rights reserved)；
• Norway の地形データ © Kartverket；
• United Kingdom の地形データ © Environment Agency copyright and/or database right 2015. All rights reserved；
• United States 3DEP（旧 NED）および全球 GMTED2010 と SRTM の地形データは、U.S. Geological Survey の厚意により提供されています。

このサーバーは、米国地質調査所および Open Topo Data から独立しており、いずれからも推奨を受けていません。

貢献

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

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。