openstreetmap-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 技能介绍地点解析、空间查询、分页，以及如何解读覆盖范围和标签结果。

在规范校验前会接受参数别名：附近查询和反向查询中，latitude / longitude 可代替 lat / lon；附近查询中，radius_m 可代替 radius_meters；搜索中，q 可代替 query。请任选一种写法，不要同时使用两种。radius、tag 和 tags 仍为无效参数；公布的模式使用规范名称。

openstreetmap_search_places _工具

• 使用自由格式的 query 或结构化字段 street、city、county、state、country、postalcode，两者不能同时使用；最多返回 40 条结果（limit 默认值为 5；若 limit 更大，则按 40 处理，并返回 limitNotice），可通过 countrycodes、layer、featureType 和 viewbox 缩小范围（使用 bounded: true 进行限制）
• 结果包含坐标、结构化的 address、boundingbox、importance 以及 osm_type + osm_id；extratags 会添加联系信息和物理属性标签；若第一页无结果，则以 no_results 失败
• 返回整页结果时会提供 nextExcludeIds，供后续请求作为 exclude_place_ids 传回；结果耗尽后会返回零条结果和提示，而不是错误

---

openstreetmap_reverse_geocode _工具

• 使用 lat / lon，并通过 zoom 指定缩放级别，范围为 3（国家）到 18（建筑，默认值）；layer 默认为 address,poi
• 返回最近的已编入索引的对象，包含结构化的 address、osm_type + osm_id 和 boundingbox；没有 OSM 数据的坐标会以 no_coverage 失败

---

openstreetmap_lookup_objects _工具

• 最多接受 500 个 osm_ids 条目，每个条目必须以 N、W 或 R 开头（["N240109189"]）；格式错误的 ID 会以 invalid_id_format 失败
• 查询前 50 个不重复的 ID；其余 ID 会作为 deferred_ids 返回，供下次调用使用
• 返回找到的对象的地址记录，并将其余对象列在 not_found 下（包括 Nominatim 未编入索引的对象，例如路灯）；notice 中包含一条 openstreetmap_query_raw 查询，可用于检查哪些对象存在

---

openstreetmap_query_nearby _工具

• 使用 lat / lon 和 radius_meters，半径上限为 50,000（默认值为 1,000）；指定一个主标签 amenity，或指定 tag_key 和可选的 tag_value，并可添加最多五个以 AND 连接的 filters；每页最多返回 500 个要素（若 limit 更大，则按 500 处理，并返回 limitNotice）
• 默认情况下，值必须完全匹配；list_item 模式（通过 tag_value_match 指定，或在过滤条件中使用 match）会匹配分号分隔列表中的单个项目，因此 cuisine = pizza 也会找到 cuisine=pizza;italian
• 如果某个 amenity 值在 OpenStreetMap 中使用其他键标记（amenity: "museum"；博物馆使用 tourism=museum），则会返回 notice，指出应改用的键
• 要素包含 osm_type + osm_id、坐标、distance_meters（到要素最近点的距离）以及完整标签集，并按距离从近到远排序；effectiveTag 会回显过滤链

---

openstreetmap_query_bbox _工具

• 每次调用只能指定一个范围：角点 south、west、north、east，或 within 加一个 R/W 边界引用（R237385），该引用由地理编码结果中的 osm_type + osm_id 构成；标签过滤、列表项匹配、无效 amenity 提示以及每页最多 500 条的限制均与 openstreetmap_query_nearby 相同
• effectiveArea 会回显 within 的解析结果，areasTimestamp 会显示区域数据的时效；未映射到区域的引用会返回空页和提示
• west 大于 east 表示边界框跨越国际日期变更线；south 大于 north 会以 invalid_bbox 失败

---

openstreetmap_query_raw _工具

• 可使用任何包含 [out:json] 的 Overpass QL；[timeout:N] 根据 timeout_seconds 设置（上限为 180，默认值为 30）；如果查询未设置 [maxsize:268435456]（256 MiB），则会自动添加；每页最多返回 500 个元素（若 limit 更大，则按 500 处理，并返回 limitNotice）
• 返回原始元素（way 包含 nodes[]，relation 包含 members[]），以及 total_elements 和实际发送的 effectiveQuery；格式错误的 QL 会以 query_error 失败，并附上 Overpass 的解析错误
• 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，以遵守每秒一次请求的策略；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 可将服务指向自托管或镜像实例

适合 Agent 使用的输出：

• effectiveQuery、effectiveTag 和 effectiveArea 会回显实际发送的内容；Overpass 响应会添加 data_timestamp 和 servingEndpoint，且每个响应都会包含 ODbL attribution
• 任意工具返回的 osm_type + osm_id 都可传给 openstreetmap_lookup_objects；地理编码得到的 relation 或 way 可转换为 within 引用，供 openstreetmap_query_bbox 使用
• 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	将所有查询固定到一个 Overpass 端点，并禁用故障转移。	未设置
OSM_OVERPASS_ENDPOINTS	以逗号分隔、按顺序排列的 Overpass 端点；多于一个端点时会启用故障转移。设置 OSM_OVERPASS_BASE_URL 时会忽略此项。	https://overpass-api.de/api/interpreter
OSM_OVERPASS_MAX_CONCURRENCY	每个端点允许同时执行的 Overpass 查询数上限。公共实例允许每位用户同时执行一个查询。	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 运营的主实例。在 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；消息中会说明每个端点的结果
• servingEndpoint、错误消息和日志中仅报告端点的来源地址（https://overpass-api.de）
• 额外条目仅用于故障转移，不会增加并发数。对于允许并行查询的实例，在条目后附加 |N，表示 N 个槽位（https://mirror.example/api/interpreter|4）；URL 中的字面 | 请写作 %7C。切勿为公共 FOSSGIS 服务器设置并发数
• 等待槽位的调用若排队满 30 秒，会以 pacer_shed 失败，且 retryAfter 至少为 30 秒

添加端点意味着将查询发送给第三方。请在 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 的六个工具。
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 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不捏造缺失字段

贡献

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

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参阅 LICENSE。

地图数据由 OpenStreetMap 贡献者提供，采用 Open Database License（ODbL）。