概览

OpenStreetMap通过Nominatim和Overpass API的数据. Geocode 定位和地址,将坐标解到最近的地址,查找已知的OSM对象,并通过在某个点周围,一个边框内,或者在OSM边界内标记来查询特征.

工具

能力参考

这个 openstreetmap-guide 技能包括定位解析、空间查询、寻呼、解释覆盖范围和标记结果.

在犬科鉴定前接受参数化名: latitude 编号 : longitude 页:1 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,则a viewbox (限制使用 bounded: true(中文(简体) )
• 结果带坐标,结构 address, (中文(简体) ), boundingbox, (中文(简体) ), importance,以及 osm_type + 键 osm_id· ; extratags 添加联系人和物理属性标记; 空出第一页失败 no_results名称 countrycodes, (中文(简体) ), layer, (中文(简体) ), featureType边框 viewbox 发送
• 每页都有结果返回 nextExcludeIds 转回为 exclude_place_ids,因为比 limit 还可以有更多。 一旦结果耗尽, 就会得到零结果和通知, 而不是错误, 并且对实例的 URL 限制走得太长 失败 request_too_long

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个独特的身份被查;其余的作为 deferred_ids 下一个呼叫
• 返回所找到对象的地址记录并列出其余内容 not_found (包括物体Nominatim不指数,例如街道灯;a) notice 携带一个 openstreetmap_query_raw 要检查是否存在的查询

openstreetmap_query_nearby _工具

• lat 编号 : lon 与 radius_meters 最多50,000(默认为1,000);一个主标签, amenity 或者说 tag_key 带有可选 tag_value,加上最多5个 filters; 每页最多500个特性( 较大) limit 以500为单位 limitNotice(中文(简体) )
• element_types 除非设置,否则要搜索节点、方式和关系; ["node", "way"] 断绝关系
• 默认的数值完全匹配; 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 响应过滤链
• 通过搜索方式或关系,一个包含点的区域,如它所在的公园或城市,匹配在 distance_meters 0,无论半径,和 areasTimestamp 说地区数据有多老 无法运行区域搜索的结束点会被再次询问,没有它 notice 表示未检查含有此点的区域

openstreetmap_query_bbox _工具

• 每个呼叫范围:角 south, (中文(简体) ), west, (中文(简体) ), north, (中文(简体) ), east,或 within 和一个 R编号 :W 边界参考文件(R237385由地理编码结果制成 osm_type + 键 osm_id; 相同的标签过滤器, 列表项匹配, 出错 --amenity 通知,每页500个上限为 openstreetmap_query_nearby
• element_types 除非设置,否则要搜索节点、方式和关系; ["node", "way"] 断绝关系
• effectiveArea 命名边界 within 达到的目标 name, (中文(简体) ), boundary,以及 admin_level 标记,然后是它所绘制的Overpass区域,所以一个打错了的 ref 显示; areasTimestamp 表示区域数据的历史; 将区域映射到没有区域时, 返回空页并带有通知
• A 类 west 大于 east 是一个穿越时空的盒子; south 大于 north 失败为 invalid_bbox

openstreetmap_query_raw _工具

• 任何包含 [out:json]· ; [timeout:N] 来自 timeout_seconds (最多180个,缺省30个)和 [maxsize:268435456] (256 MiB) 当查询设置为无时会被添加;每页最多500个元素(较大) limit 以500为单位 limitNotice(中文(简体) )
• 返回原始要素(载体) nodes[]关系 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和可流式的 HTTP 传输器,可插接式(none 编号 : jwt 编号 : oauth),可互换存储(in-memory, (中文(简体) ), filesystem, (中文(简体) ), Supabase, (中文(简体) ), Cloudflare KV/R2/D1),结构化记录,可选择的OpenTeleometry tracking.

OpenStreetMap 特异性 :

• 诺米纳蒂姆请求的间隔为1,050毫秒,以遵守其每秒一次请求的政策; OSM_USER_AGENT 将服务器识别为两个上游
• 每个端点限制过路查询 OSM_OVERPASS_MAX_CONCURRENCY,则选择进入失败 OSM_OVERPASS_ENDPOINTS (见 逾越终点故障(中文(简体) )
• 过关工具页面 limit 财务报告和审定财务报表 offset 报告 totalFound, (中文(简体) ), truncated,以及 nextOffset;结果被缓存了10分钟( Nominatim for 60),所以重传不会产生新的上游请求
• 超过 64 MiB 的过关响应失败 result_too_large
• OSM_NOMINATIM_BASE_URL 财务报告和审定财务报表 OSM_OVERPASS_BASE_URL 将服务器指向自托管或镜像实例

方便代理输出 :

• effectiveQuery 财务报告和审定财务报表 effectiveTag 呼应所发送的 effectiveArea 命名边界 a within 已到达 ; 超时回复 添加 data_timestamp 财务报告和审定财务报表 servingEndpoint,每个响应都带有ODbL attribution
• osm_type + 键 osm_id 从任何工具种子中 openstreetmap_lookup_objects,而地理编码关系或方式成为 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 或源构建,请参见 运行服务器。 。 。 .

配置

见 .env.example 用于完整可选覆盖列表。 任意的无效值 OSM_* 变量在启动时停止服务器,并带有一个给变量命名的信息.

逾越终点故障

默认每个Overpass查询都到一个终点,即自由和开放源码软件操作的主要实例。 列出更多 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 输入https://mirror.example/api/interpreter|4用于 N 槽; 写一字形 | 在 URL 中作为 %7C。永远不要大小化公共实例(自由和开放源码软件服务器、地图.mail.ru、overpass.private.coffee)
• 呼叫等待槽失败 pacer_shed (单位:千美元) retryAfter 30秒后至少30秒

添加端点会向第三方发送您的询问 。 请检查url=值 (帮助) OSM 维基实例列表,确认它持有全球数据(一个区域实例用空的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 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 于 http://localhost:3010/mcp 在无国籍人会话模式和日志中 /var/log/openstreetmap-mcp-server。默认情况下安装了 OpenTeleometry 端对接点; 构建为 --build-arg OTEL_ENABLED=false 以略去他们。 运行时间遥测直到通过 -e OTEL_ENABLED=true。 。 。 .

项目结构

发展指南

见 CLAUDE.md 发展准则和建筑规则。 简本:

• 搬运工投掷,框架渔获量——否 try/catch 在工具逻辑中
• 使用 ctx.log 用于伐木, ctx.state 用于存储
• 登记册中的新工具 createApp() 数组在 src/index.ts
• 环绕外部 API 调用: 验证 生 → 规范到域类型 → 返回输出计划; 永远不要编织缺失的字段

捐款

问题值得欢迎。 提交前进行检查和测试:

bun run devcheck
bun run test

许可证

阿帕奇-2.0 — 见 自由主义 详细情况.

地图数据来源 OpenStreet地图 捐款者,在 开放数据库许可证( ODbL)。 。 。 .