overspan-mcp
An MCP (Model Context Protocol) server for Overspan, the hosted Overpass API. It gives Claude, Cursor, and any other MCP client direct, metered access to full-planet OpenStreetMap data: raw Overpass QL plus helper tools for nearby search, bounding-box search, counting, and usage checks.
You need an Overspan API key. Plans start at $19/month at overspan.dev; the key arrives by email after checkout, no account needed.
Quickstart
Claude Code
claude mcp add overspan --env OVERSPAN_API_KEY=YOUR_KEY -- npx -y overspan-mcp
Claude Desktop, Cursor, and other JSON-configured clients
{
"mcpServers": {
"overspan": {
"command": "npx",
"args": ["-y", "overspan-mcp"],
"env": {
"OVERSPAN_API_KEY": "YOUR_KEY"
}
}
}
}
The key must be in the server's env block. MCP clients start servers with their own environment, so a variable exported in your shell profile will not reach it. Treat any config file containing the key as a secret; in Claude Code's .mcp.json you can write "OVERSPAN_API_KEY": "${OVERSPAN_KEY}" to keep the key in your environment and out of the file.
Tools
| Tool | What it does |
|---|---|
overpass_query | Run a raw Overpass QL query. The escape hatch when the helpers are too narrow. |
find_nearby | Features matching tag filters within a radius of a point. |
features_in_bbox | Features matching tag filters inside a bounding box. |
count_features | Count matches in an area without returning them. Cheap; use it before pulling data. |
get_usage | The key's tier, limits, month-to-date quota, and recent requests. Never consumes quota. |
The server also exposes two resources the model can read (overspan://overpass-ql, a QL cheat sheet, and overspan://differences, how Overspan differs from the public servers) and one prompt (write-bounded-overpass-query).
Behaviour worth knowing
- The key is sent as an
Authorization: Bearerheader, never in a URL. - Every successful tool result carries a quota line (
[quota] 49998 of 50000 monthly requests remaining) so an agent can pace itself.get_usagegives the full picture and is free to call. - Errors come back in plain language with the gateway's error code, what it means, and whether to retry. Rejected requests do not consume quota, and a runaway loop is bounded by the key's own rate and concurrency caps, never by a larger bill.
- Oversized responses are trimmed to fit a model's context: for Overpass JSON the element list is cut and the result says how many elements were dropped. Raise the cap with
OVERSPAN_MAX_RESPONSE_CHARSif you want more. - Queries without
[timeout:]get 25 seconds. Set it explicitly for heavy queries, up to your tier's cap.
Environment variables
| Variable | Required | Default | Purpose |
|---|---|---|---|
OVERSPAN_API_KEY | yes | Your Overspan API key | |
OVERSPAN_API_URL | no | https://api.overspan.dev | Override the API endpoint |
OVERSPAN_MAX_RESPONSE_CHARS | no | 48000 | Truncation threshold for tool results |
Data licence
Results are OpenStreetMap data, licensed under the Open Database License. Anything you publish that shows or derives from this data needs a visible credit reaching openstreetmap.org/copyright. Your Overspan subscription pays for hosting and access, not for the data, and does not change those obligations.
Development
npm install
npm run build
npm test
The test suite covers the query builders, response shaping, error mapping, and a full in-memory MCP client round trip.
Links
Overspan is an independent service, not affiliated with the OpenStreetMap Foundation or the Overpass API project.
MIT licensed.