AtlasFetch

atlasfetch-mcp

**无需注册即可试用：**没有密钥时，会回退到共享的公共演示密钥，所有使用者每月合计最多可查询 1,000 次。前往 atlasfetch.xyz 免费注册，即可获得专属额度。

这是一个用于 AtlasFetch 的 MCP 服务，提供逆地理编码到行政区划和街道，以及地理围栏功能，作为工具供 AI 助手直接调用。

询问“坐标 -33.9249, 18.4241 位于哪个市镇？”，即可通过真实的点在多边形内查询，而不是依赖模型的记忆，获得带有 ISO 3166 代码的南非西开普省开普敦。

country: United Kingdom (GB) · region: England (GB-ENG) · municipal: City of Westminster (GB-WSM)

功能

工具	功能
lookup_location	将坐标解析为包含该坐标的国家、地区和市镇，并提供 ISO 3166-1 / 3166-2 代码，以及与你自己的边界集匹配的结果。还可选择返回最近的街道（请求 street 图层），以及以 H3 单元格或 Google Plus Code 表示的点位。
geocode_address	将地址解析为一个点位，目前仅支持南非，并提供精度，说明找到的是房屋、街道，还是仅有郊区，以及接下来该怎么做。
get_route	计算 2 到 25 个坐标之间的驾车、骑行、步行或卡车路线，并提供逐向导航步骤；还可选择绕开你自己的区域，或测量路线在这些区域内的长度。
list_boundary_sets	列出你的边界集、各自的数量，以及哪些 API 密钥可以查询它们。
create_boundary_set	为你自己的多边形创建一个空边界集。
add_boundary	添加一个 GeoJSON 多边形，并在每次匹配时返回其属性。
update_boundary	移动或调整一个边界的形状，同时保留其 ID、名称和属性。

**适用场景：**逆地理编码到行政区域、查找点位所在的街道、针对你自己的配送区或服务区进行地理围栏检查、辖区和区域核查、为位置数据添加区域代码、对南非的配送地址进行地理编码，以及规划避开指定区域的路线。

**不适用场景：**南非以外的地理编码（暂不支持）、按名称搜索地点、考虑实时交通的预计到达时间、距离矩阵、等时圈、地图切片或下载边界几何数据。

路线规划

get_route 会计算 2 到 25 个坐标之间的路线，并返回距离、耗时和逐向导航步骤，支持 car、bike、foot 或 truck。

car: 3.5 km · 5 min · 11 steps · a location moved 62 m to reach a road — free-flow, no traffic

接入前有三点值得了解：

• 每条路线消耗 10 次查询，而不是 1 次。返回的所有信息都包含在其中，但费用是单次查询的 10 倍。
• 耗时按畅通路况计算——按路网自身的限速行驶，不考虑实时或历史交通。这不是预计到达时间。如需此类信息，请使用支持交通状况的服务。
• 默认不返回路线线条（routeGeometry: "none"）。编码后的折线长达数千个字符，助手无法阅读；只有在需要绘制路线时，才请求 polyline6 或 geojson。

让路线避开或经过你自己的区域。 avoidSets 指定需要绕行的边界集；exposureSets 指定要进行测量的边界集，路线保持不变，同时报告路线在各区域内行驶的米数。如果某个区域包含你提供的位置，则无法让该路线避开此区域；系统会跳过该区域，并在结果中说明。

额度限制适用：免费套餐最多支持 2 个位置，Pro 最多支持 25 个位置；卡车路线仅限 Pro，备选路线必须恰好提供 2 个位置。超过上限时，结果会返回 403，且不会扣费；如果某个位置附近没有道路，则会返回 422，并且会扣费，因为系统已尝试规划路线。

地理编码

geocode_address 可将一个地址转换为一个点：在一行中传入 q，或传入已拆分为各部分的 address。目前支持南非。

address · confidence 0.96 · 25 Adderley Street, Cape Town, ZA-WC — dispatch
street · confidence 0.47 · ambiguous · Long Street, Cape Town, ZA-WC — ask the customer before dispatching

使用这个点之前，请先查看精度。 address 表示门牌地址；interpolated 表示根据前后门牌号估算的位置；intersection 表示街道拐角（“Cnr Main Rd and Belmont Rd”）；site 表示有名称的地点，例如购物中心、商务园区或医院（请将商店或单元号告知司机）；street 表示街道正确，但未精确到门牌；locality 仅表示郊区。结果行会根据 API 自身的建议处理配送：只有在结果精确到门牌、街角或地点且没有歧义时才派送；若结果仅精确到街道，请收件人提供定位；若结果有歧义，请联系客户。南非的大多数结果都只精确到街道，因为 OpenStreetMap 中只有约 13% 的街道名称包含门牌号。

每次调用只查询一个地址，每次查询计 1 次，无论是否找到结果。这是刻意设计的：配送清单会逐行处理，方便你查看用量。需要处理数千行的程序应直接调用 API 的 POST /geocode/batch。

街道

添加 street 图层后，结果会包含最近的街道，以及有地图数据时的门牌号。此功能覆盖全球，且需主动启用，不属于默认的 country, region, municipal 图层。

你始终会获得三个结果：分别对应 5 m、20 m 和不限距离，因为“最近的街道”取决于你愿意搜索多远：

"street": [
  { "radiusMeters": 5,    "streetNumber": null, "streetName": "Adderley Street", "postcode": null,   "distanceMeters": 2.7 },
  { "radiusMeters": 20,   "streetNumber": "25", "streetName": "Adderley Street", "postcode": "8001", "distanceMeters": 9.6 },
  { "radiusMeters": null, "streetNumber": "25", "streetName": "Adderley Street", "postcode": "8001", "distanceMeters": 9.6 }
]

两个含义不同的 null： "street": null 表示该国家没有街道数据；某个字段均为 null 的条目则表示在该距离范围内没有结果。streetNumber 和 postcode 是字符串（44A、12-14、0181）；在地图数据不完善的地区以外，门牌号很少见。设置 streetGeometry 后，每个结果还会包含街道线条，截取长度约为 250 m。除非有东西要绘制，否则请勿启用。

安装

Claude Code

claude mcp add atlasfetch -- npx -y atlasfetch-mcp

Claude Desktop、Cursor、VS Code 和其他客户端

将以下内容添加到 MCP 配置中（claude_desktop_config.json、.cursor/mcp.json 或客户端对应的配置文件）：

{
  "mcpServers": {
    "atlasfetch": {
      "command": "npx",
      "args": ["-y", "atlasfetch-mcp"],
      "env": {
        "ATLASFETCH_API_KEY": "your-key-here"
      }
    }
  }
}

需要 Node 20 或更高版本。

获取密钥

演示密钥由互联网上所有匿名用户共享，共用一个配额和速率限制。适合初步体验，但不适用于实际用途。

在 atlasfetch.xyz/dashboard 创建自己的密钥，并设置 ATLASFETCH_API_KEY。免费 Personal 计划无需绑定银行卡。你可以随时在控制面板中复制密钥，因此请在那里将密钥限制为仅适用于自己的域名。2026 年 10 月 12 日之前创建的密钥已被撤销；如果你的密钥停止工作，请复制一个仍有效的密钥。

变量	默认值	用途
ATLASFETCH_API_KEY	(演示密钥)	你的 API 密钥。
ATLASFETCH_API_URL	https://api.atlasfetch.xyz	仅用于本地或预发布 API 的覆盖设置。

两件容易让人意外的事

municipal 是可用的最细级别，并非始终代表同一类区域。 洛杉矶会返回城市，堪萨斯州的乡村地区会返回县，有些地方则会返回行政区。若某个国家的精细级别数据不完整，系统会改用数据完整的较粗级别，因为在大多数用途中，县总比 null 好。不要假设该值一定是城市名称。

无法通过此服务让新的边界集变为可查询。 边界集创建后默认处于停用状态，且不会授予任何密钥；授权时需要 API 密钥 id，而只有已登录的浏览器会话才能列出该 ID。因此，此服务可以创建边界集并填充数据，但最后一步必须在控制面板中完成。create_boundary_set 会在响应中说明这一点，不会让你得到一个悄无声息地匹配不到任何内容的边界集。

计费

一次查询或一个地理编码地址计为一次查询；标准套餐中，一条路线计为 10 次查询。无论一次查询涉及多少图层、集合或网格代码，都只计为一次。计量发生在匹配之前，因此，即使查询没有匹配到任何内容，也会计费。被拒绝的无效请求或超出速率限制的请求不会计费。

约定

以下规则适用于全部七种工具，因此同一种输入在任何地方都表示相同的含义。

• set 表示一个集合，sets 表示多个集合。 add_boundary 和 update_boundary 操作一个集合（set）。lookup_location 和 geocode_address 会与任意数量的集合（sets）进行匹配。

• get_route 会展平两个 API 对象。 API 接受 avoid: { sets: [...] } 和 exposure: { sets: [...] }。工具使用 avoidSets 和 exposureSets，因为模型容易弄错只有一个键的包装对象。

• …Geometry 始终表示你要求返回的线，并且默认关闭。 get_route 中的 routeGeometry，以及 lookup_location 和 geocode_address 中的 streetGeometry。普通的 geometry 输入则是你传入的多边形，适用于 add_boundary 和 update_boundary。（get_route 仍接受 geometry 作为 routeGeometry 的旧名称；该名称将在 1.0 中移除。）

• 如果默认值与 API 不同，那是有意为之：

  工具	输入	此服务	API	原因
  get_route	steps	true	false	用户向助手询问路线时，通常需要逐向导航
  lookup_location	streetGeometry	将 street 添加到 base	没有 street 时返回 400	请求街道的线形几何，就表示需要这条街道

• 每个回答的第一行是写给人的，不构成接口约定。 它会概括回答并说明如何使用（— dispatch、— ask the customer），其措辞也会持续改进。下方的 JSON 是 API 原样返回的回答，应以此为准进行解析。

稳定性

在 1.0 之前，次版本（0.3 → 0.4）可能会重命名或移除输入项，就像 0.4.0 所做的那样；但始终会先提供已弃用的别名。

从 1.0 起：

• **冻结：**工具名称、输入名称、输入类型和默认值。
• **次版本发布中可能变更：**新增工具、新增可选输入、新增输出可取值（例如 precision 新增了 intersection 和 site），以及描述和每个回答第一行的措辞。
• **破坏性变更会通过弃用流程处理。**旧形式至少会继续有效一个次版本，其描述会说明替代形式，并且只会在下一个主版本中移除。
• 每个回答中的 JSON 都遵循 AtlasFetch API；该 API 会在自己的 OpenAPI 规范 中对接口约定进行版本管理。

每个版本的变更都记录在 CHANGELOG.md 中。

开发

npm install
npm run build
node scripts/smoke.mjs   # drives the built server with a real MCP client, against the live API

链接

• 文档 · OpenAPI 规范 · llms.txt
• Playground — 无需注册即可试用查询

许可证

此服务采用 MIT 许可证。参考边界数据源自 OpenStreetMap，受 ODbL 许可；署名和相同方式共享义务也适用于你。你查询的坐标不会被存储。