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	判断地形是否阻挡两点之间的视线，考虑地球曲率和折射；还可检查无线电链路的第一菲涅耳区净空

能力参考

每个成功的结果都会在两个响应表面上包含 vertical_reference。公共 SRTM 使用 EGM96；美国本土 3DEP 通常使用 NAVD88，但返回栅格的基准未经验证，其他地区也可能不同。Mapzen 和自托管的 Open Topo Data 的基准未知或不固定。只有无数据的结果无法确定高度基准。返回的高度未经转换；混合数据集不会统一到同一基准。water_surface_m 需要兼容的地形基准；仅凭零值或 source: opentopodata 无法确认兼容性。

elevation_get_points _工具

• points：1–1,000 个 {lat, lon} 对象，使用十进制度（WGS84），也可以是单个点。仅验证并采样前 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。路径长度不足 1 米时失败，错误为 degenerate_path；路径经过对跖点时失败，错误为 antipodal_path（请在已标识的零起始索引输入顶点之间添加中间航点）；没有任何采样点有数据时失败，错误为 no_coverage
• include_samples（默认 true）会返回 samples[]（每个采样点的距离、位置、海拔、坡度、数据集和分辨率）；设为 false 时会省略该字段和采样表，其余结果不变

---

elevation_get_grid _工具

• south、west、north、east：边界，使用十进制度（边界框不能跨越经度 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。端点间距不足 1 米、超过 1,000 km 或端点无数据时失败，错误分别为 same_endpoints、sightline_too_long 或 endpoint_no_data
• 设置 frequency_mhz 后会添加 fresnel：根据第一菲涅耳区 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 s；如果其给出的等待时间不超过一天，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 s 采样时间预算耗尽（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 覆盖范围内查询 3DEP，并将 3DEP 未命中和覆盖范围外的请求发送到 Open Topo Data；usgs_3dep 和 opentopodata 则固定使用单个提供方。只有覆盖范围未命中时才会回退，服务中断时不会回退
• Open Topo Data 先从 SRTM GL1 v3 获取响应（约 30 m，覆盖北纬 60° 到南纬 56° 之间的陆地），然后在 SRTM 没有数据块时使用 Mapzen 地形图块：高纬度地区、南极洲和海洋水深数据
• 每次调用上限为 100 个点或 250 个采样点或网格单元，采样时间预算为 45 s；每个 3DEP 点单独发起请求（并发数为 6，每秒最多 10 个），而 Open Topo Data 每个请求接收 100 个点
• 公共 Open Topo Data 实例会按照其公布的限制控制请求速率：一次只发起一个请求，每次请求开始时间至少间隔 1.1 s，每个服务进程在过去 24 小时内最多发送 1,000 个请求
• 剖面、网格和视线均根据点采样结果在本地计算，采用大圆距离和重采样，并考虑标准折射率下的地球曲率

便于 Agent 使用的输出：

• 每个值都标明来源：每个点、剖面采样点、网格单元和视线点都会标出其 dataset（usgs_3dep、srtm30m、mapzen），除 Mapzen 外还会标出其 resolution_m（剖面和网格使用 resolution_m_range）；计算结果还会添加 datasets_used 计数，并用 Sources: 行注明提供响应的所有数据集
• 缺失数据保持缺失：没有数据的点或采样点会省略其高程，网格单元则为 null，绝不会设为 0；摘要会报告有数据的值的数量
• 提示会标明影响结果解读的情况：结果混合使用 3DEP 和 Open Topo Data、Mapzen 值低于 0 m（海底深度）、视线上 3DEP 值低于 0 m、采样间距粗于或细于数据源分辨率、净空裕度较小，以及无线电路径通畅但菲涅尔净空不足 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,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 均无需密钥。
• 可选：自托管 Open Topo Data 实例，并配备 srtm30m 和 mapzen 数据集，适用于大量请求或托管场景（参见配置）。

安装

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 的公开限额。 公共实例允许每个请求包含 100 个位置，每秒 1 个请求，并且每个 IP 地址每天最多 1,000 个请求。每个服务进程都会自行控制请求频率，但计数仅限于进程本地，并会在重启后重置。同一台机器上的多个进程（每个客户端会话各运行一个 stdio 服务），或使用同一地址的其他客户端，也会占用上游的计数，因此上游可能会先拒绝请求（opentopodata_rate_limited）。
• 共享部署。 为许多用户提供服务的部署会从同一地址发送所有请求，因此在公共实例上，这些用户共享每天 1,000 次的额度：约可查询 1,000 个点，或进行 333 次完整的 250 点采样调用；如果重试也会消耗请求，则可能只有 111 次。额度耗尽后，所有需要 Open Topo Data 的调用在最长 24 小时内都会失败，并返回 opentopodata_daily_limit；即使是只遇到一个 3DEP 未命中点的 auto 调用也不例外。因此，此类部署上的全球数据结果只能尽力提供；将 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 的水域数值取决于栅格类型：可能是经过水文平坦化的地表、海平面或水深。对于低于 0 的 Mapzen 数值，视线分析会按 0 m 计算净空；对于收到的低于 0 m 的 3DEP 数值，则会照原样使用，因为 USGS 的响应不会说明海湾底部还是低于海平面的旱地；其提示会标记这些数值，而 water_surface_m 则会测量水面上方的视线。
• 混合模型。 3DEP 是裸地 DEM，在美国本土通常采用 NAVD88；返回栅格的具体基准未经验证，且在其他地区可能有所不同。公开的 SRTM 是雷达地表模型，部分包含树冠和建筑物，并采用 EGM96。Mapzen 混合了区域数据源；可自托管的数据集名称无法验证其基准。高度不会转换到统一的高程基准，基准差异本身也无法解释不同提供方之间的差异。
• 采样。 小于采样间距的地物会被漏掉：例如，视线采样点之间的山脊、网格节点之间的山峰（围绕 summary.highest 对更小的区域重新生成网格，以提高精度），以及剖面采样点之间的短距离爬升。系统始终会报告间距。
• USGS 3DEP 吞吐量。 点查询服务没有公布限额，也没有批量查询端点：按此服务器的请求频率控制，每秒约可查询 10 个点，因此设有 250 个采样点的上限和 45 s 的预算。如果某次调用的查询会使队列超过正在运行的调用的预算，系统会立即拒绝该请求并返回 sampling_deadline_exceeded 和 data.retryAfter。因此，同时发起的两个 250 点采样调用会依次运行：第二个调用可在约 25 s 后重试。
• 来自 USGS 的采集日期会以原始的 M/D/YYYY 格式传递，有时月份或日期会带有零；其他格式的日期会被省略。
• 国际日期变更线。 网格区域不能跨越经度 180，因此请拆分为两个调用。跨越该线的路径和视线可正常处理。
• 视线分析的距离上限为 1,000 km；在此距离下，抛物线曲率近似会使中点隆起高度最多被高估约 10 m。其菲涅耳区检查仅针对所选地球模型下的第一菲涅耳区与 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() 入口：注册四个工具，根据配置构建服务指令，并启动和释放高程服务。
src/config	使用 Zod 解析和验证 OPENTOPODATA_BASE_URL。
src/mcp-server/tools/definitions	工具定义（*.tool.ts）。
src/mcp-server/tools/shared	四个工具共用的输入架构、输出架构和 format() 辅助函数。
src/services/elevation	ElevationSampler（路由、3DEP 覆盖范围、单次调用预算）、几何、归属信息和单位辅助函数。
src/services/usgs-epqs	USGS 高程点查询服务客户端。
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 高程点查询服务	公共领域（美国联邦政府作品）。请注明美国地质调查局（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 地形图块归属信息逐字引自 tilezen/joerd 归属信息文档：

• ArcticDEM 地形数据 DEM(s) 使用 DigitalGlobe, Inc. 的影像创建，并由国家科学基金会奖项 1043681、1559691 和 1542736 资助；
• 澳大利亚地形数据 © 澳大利亚联邦（Geoscience Australia）2017；
• 奥地利地形数据 © offene Daten Österreichs – Digitales Geländemodell (DGM) Österreich；
• 加拿大地形数据包含根据《加拿大开放政府许可证》授权的信息；
• 欧洲地形数据使用欧盟资助的 Copernicus 数据和信息制作——EU-DEM 图层；
• 全球 ETOPO1 地形数据：美国国家海洋和大气管理局
• 墨西哥地形数据来源：INEGI，Continental relief，2016；
• 新西兰地形数据版权归 Crown copyright (c) Land Information New Zealand 和新西兰政府所有，2011（保留所有权利）；
• 挪威地形数据 © Kartverket；
• 英国地形数据 © Environment Agency，版权和/或数据库权利 2015。保留所有权利；
• 美国 3DEP（前身为 NED）、全球 GMTED2010 和 SRTM 地形数据由美国地质调查局提供。

本服务独立于美国地质调查局和 Open Topo Data，且未获任何一方认可。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

本项目根据 Apache 2.0 许可证授权。详情请参阅 LICENSE 文件。