overspan-mcp
overspan-mcp
一个用于 Overspan 的 MCP(模型上下文协议)服务器,Overspan 是托管的 Overpass API。它为 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-mcpClaude 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}",将密钥保留在环境中,而不写入文件。
Related MCP server: @cyanheads/openstreetmap-mcp-server
工具
工具 | 作用 |
| 运行原始 Overpass QL 查询。当辅助工具过于局限时的逃生舱。 |
| 在点半径内匹配标签过滤器的要素。 |
| 在边界框内匹配标签过滤器的要素。 |
| 统计区域内的匹配数量而不返回它们。成本低;在拉取数据前使用。 |
| 密钥的层级、限制、本月至今的配额以及最近的请求。从不消耗配额。 |
服务器还暴露了两个模型可读取的资源(overspan://overpass-ql,一个 QL 速查表,以及 overspan://differences,说明 Overspan 与公共服务器的差异)和一个提示(write-bounded-overpass-query)。
值得了解的行为
密钥通过
Authorization: Bearer头发送,绝不放在 URL 中。每个成功的工具结果都带有配额行(
[quota] 49998 of 50000 monthly requests remaining),以便代理自行调整节奏。get_usage提供完整信息,且调用免费。错误以通俗语言返回,包含网关的错误代码、含义以及是否重试。被拒绝的请求不消耗配额,失控循环受密钥自身的速率和并发上限约束,绝不会导致更大的账单。
过大的响应会被截断以适应模型的上下文:对于 Overpass JSON,元素列表会被截断,结果会说明丢弃了多少元素。如果需要更多,可以通过
OVERSPAN_MAX_RESPONSE_CHARS提高上限。没有
[timeout:]的查询默认获得 25 秒。对于重型查询,请显式设置,最高可达你的层级上限。
环境变量
变量 | 必需 | 默认 | 用途 |
| 是 | 你的 Overspan API 密钥 | |
| 否 |
| 覆盖 API 端点 |
| 否 |
| 工具结果的截断阈值 |
数据许可
结果是 OpenStreetMap 数据,根据 开放数据库许可证 授权。你发布的任何展示或衍生自这些数据的内容都需要可见的署名,指向 openstreetmap.org/copyright。你的 Overspan 订阅支付的是托管和访问费用,而非数据本身,并且不会改变这些义务。
开发
npm install
npm run build
npm test测试套件涵盖查询构建器、响应整形、错误映射以及完整的进程内 MCP 客户端往返。
链接
Overspan 是一项独立服务,与 OpenStreetMap 基金会或 Overpass API 项目无关。
MIT 许可。
Available Tools
5 toolscount_featuresCount matching featuresARead-only
Count OpenStreetMap features matching tag filters in an area without returning them. Cheap. Use this before pulling data when the result size is unknown. Give either a point (lat, lon, radius_m) or a bounding box (south, west, north, east).
Inputs: tags (required), lat, lon, east, +4 more.
features_in_bboxFind features in a bounding boxARead-only
Find OpenStreetMap features matching tag filters inside a bounding box (south, west, north, east in decimal degrees). Returns up to 'limit' elements with their tags and a centre coordinate. Keep boxes small; for city-sized areas call count_features first.
Inputs: east (required), tags (required), west (required), north (required), +2 more.
find_nearbyFind features near a pointARead-only
Find OpenStreetMap features matching tag filters within a radius of a point. Returns up to 'limit' elements with their tags and a centre coordinate. Good first tool for questions like 'what cafes are near X'. For larger or unknown result sets, call count_features first.
Inputs: lat (required), lon (required), tags (required), limit, +1 more.
get_usageCheck Overspan usage and limitsARead-only
Check this API key's tier, its limits, month-to-date quota, and recent request history. Does not consume query quota. Use it to pace yourself when running many queries.
Inputs: no named parameters.
overpass_queryRun raw Overpass QLARead-only
Run a raw Overpass QL query against the Overspan hosted Overpass API (full-planet OpenStreetMap data, minutes behind live). Use this when the helper tools are too narrow. Always bound the query to an area and cap the output (for example: out center 25;). Start with [out:json]. Queries without [timeout:] get 25 seconds. Read the overspan://overpass-ql resource for syntax and the overspan://differences resource for how this server differs from the public ones.
Inputs: query (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
find_nearby and features_in_bbox both fetch OSM features by location, but their radius-vs-bounding-box distinction is clearly explained and they cover different query shapes. overpass_query, count_features, and get_usage are each clearly separate from the helpers and from each other.
Most names use lowercase snake_case, but the conventions vary: overpass_query and features_in_bbox are noun-like, while find_nearby, count_features, and get_usage are verb-led. None are confusing, but there is no single predictable verb_noun pattern across the set.
Five tools is well-scoped for an Overpass API server: one raw query escape hatch, two standard spatial search helpers, a counting tool for sizing result sets, and a usage-monitoring tool. Each tool has a distinct role and none feel redundant.
The tool surface covers the core workflow well: count before pulling data, query by point or bounding box, and fall back to a raw Overpass query when helpers are too narrow. get_usage also covers the operational side of the hosted API, so there are no obvious dead ends.
Maintenance
Related MCP Connectors
OpenStreetMap Overpass MCP — programmatic queries against the OSM database
Query OpenStreetMap with Overpass QL, find water and food stops along routes, and check weather at arrival time. Free API key: 500 requests/day, including commercial use. [Setup and examples](https://geo.runningcat.dev/mcp?utm_source=glama&utm_medium=referral&utm_campaign=mcp_directory).
Geocoding, static maps and privacy-safe area maps from OpenStreetMap data. Hard caps, no overage.
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables programmatic queries against the OpenStreetMap database using the Overpass API.121 npmMIT
- AlicenseNot gradedqualityAmaintenanceGeocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data via MCP.802 npm9Apache 2.0
- AlicenseAqualityDmaintenanceMCP server providing structured access to OpenStreetMap data through Overpass and Nominatim APIs, enabling geocoding, nearby place searches, element queries, and tag counting without API keys.7MIT
- AlicenseNot gradedqualityCmaintenanceEnables desktop agents and clients to access geospatial services via a hosted MCP server, including OpenStreetMap queries, address and business search, POI discovery, routing, matrices, isochrones, map matching, optimization, elevation and terrain, basemap styling, spatial analysis, rendering, usage, and service status.32 npmMIT