overspan

overspan-mcp

面向 Overspan（托管式 Overpass API）的 MCP（Model Context Protocol）服务。它让 Claude、Cursor 和其他任何 MCP 客户端都能直接、按用量访问完整地球范围的 OpenStreetMap 数据：原始 Overpass QL，以及用于附近搜索、边界框搜索、计数和用量查询的辅助工具。

你需要一个 Overspan API 密钥。套餐价格从每月 $19 起，详见 overspan.dev；结账后密钥会通过电子邮件发送，无需账户。

快速开始

Claude Code

claude mcp add overspan --env OVERSPAN_API_KEY=YOUR_KEY -- npx -y overspan-mcp

Claude Desktop、Cursor 和其他使用 JSON 配置的客户端

{
  "mcpServers": {
    "overspan": {
      "command": "npx",
      "args": ["-y", "overspan-mcp"],
      "env": {
        "OVERSPAN_API_KEY": "YOUR_KEY"
      }
    }
  }
}

密钥必须放在服务的 env 块中。MCP 客户端会使用自己的环境启动服务，因此在 shell 配置文件中导出的变量不会传递给服务。请将任何包含密钥的配置文件视为机密；在 Claude Code 的 .mcp.json 中，你可以写入 "OVERSPAN_API_KEY": "${OVERSPAN_KEY}"，将密钥保存在环境中，而不是文件里。

工具

工具	功能
overpass_query	执行原始 Overpass QL 查询。当辅助工具无法满足需求时可使用此工具。
find_nearby	查找指定点一定半径范围内符合标签筛选条件的要素。
features_in_bbox	查找边界框内符合标签筛选条件的要素。
count_features	统计区域内的匹配项，而不返回它们。开销低；提取数据前请先使用。
get_usage	查询密钥的套餐级别、限额、本月至今的配额和近期请求。不会消耗配额。

该服务还提供两个模型可读取的资源（overspan://overpass-ql，QL 速查表；以及 overspan://differences，说明 Overspan 与公共服务的区别），以及一个提示词（write-bounded-overpass-query）。

值得了解的行为

• 密钥通过 Authorization: Bearer 请求头发送，绝不会放在 URL 中。
• 每个成功的工具结果都会附带一行配额信息（[quota] 49998 of 50000 monthly requests remaining），方便 Agent 控制调用节奏。get_usage 可免费调用，提供完整用量信息。
• 错误会以通俗语言返回，并附带网关错误代码、错误含义和是否应重试的信息。被拒绝的请求不会消耗配额；即使出现失控循环，也会受密钥自身的速率和并发上限约束，不会导致更高的账单。
• 超大响应会被裁剪以适应模型的上下文：对于 Overpass JSON，会截断元素列表，并说明丢弃了多少个元素。如果需要更多内容，可提高 OVERSPAN_MAX_RESPONSE_CHARS 的值。
• 未设置 [timeout:] 的查询会使用 25 秒超时。对于耗时较长的查询，可显式设置超时时间，但不能超过套餐上限。

环境变量

变量	必填	默认值	用途
OVERSPAN_API_KEY	是		你的 Overspan API 密钥
OVERSPAN_API_URL	否	https://api.overspan.dev	覆盖 API 端点
OVERSPAN_MAX_RESPONSE_CHARS	否	48000	工具结果的截断阈值

数据许可

结果属于 OpenStreetMap 数据，依据 Open Database License 授权。任何展示或基于这些数据衍生的公开内容，都必须提供清晰可见的署名，并链接至 openstreetmap.org/copyright。你的 Overspan 订阅费用用于托管和访问服务，不包含数据费用，也不会改变这些义务。

开发

npm install
npm run build
npm test

测试套件涵盖查询构建器、响应整形、错误映射，以及完整的内存 MCP 客户端往返测试。

链接

• Overspan 文档
• 错误参考
• 用量仪表板

Overspan 是一项独立服务，与 OpenStreetMap Foundation 或 Overpass API 项目均无关联。

采用 MIT 许可。