Overspan MCP

What julesmaxxx/overspan-mcp MCP server does

The julesmaxxx/overspan-mcp MCP server gives an MCP-compatible client access to OpenStreetMap data through Overspan, a hosted Overpass API. It supports both structured helper operations and direct Overpass QL, so an agent can use a narrow query interface for common searches or write a custom query when the helpers do not cover the requirement.

The service requires an Overspan API key. Plans begin at $19 per month, and the key is supplied by email after checkout. Overspan is an independent service and is not affiliated with the OpenStreetMap Foundation or the Overpass API project.

How it works

The server runs as an npm package through npx -y overspan-mcp. MCP clients launch it as a local process and provide configuration through their server definition. The server sends the key to Overspan in an Authorization: Bearer header rather than placing it in a URL.

Successful tool responses include a quota status line showing remaining monthly requests. Calls to get_usage provide the key’s tier, limits, month-to-date usage, and recent requests without consuming quota. Rejected requests do not consume quota. Responses that exceed the configured size threshold can be trimmed; Overpass JSON results report how many elements were removed.

Setup and configuration

The julesmaxxx/overspan-mcp MCP server needs OVERSPAN_API_KEY. For Claude Code, add it with the claude mcp add command and pass the package through npx. JSON-configured clients use a server entry with command: "npx", an argument of -y overspan-mcp, and the key in the entry’s env object.

Do not assume that a key exported in a shell profile will reach an MCP process launched by the client. Put it in the server environment, or use a variable reference such as ${OVERSPAN_KEY} in Claude Code configuration to keep the secret out of the file. Optional settings include OVERSPAN_API_URL, which defaults to https://api.overspan.dev, and OVERSPAN_MAX_RESPONSE_CHARS, which defaults to 48000.

Tools and capabilities

The julesmaxxx/overspan-mcp MCP server exposes these tools:

• overpass_query runs a raw Overpass QL request for queries that need more control than the helpers provide.
• find_nearby finds features matching tag filters within a radius of a coordinate.
• features_in_bbox finds tag-matching features inside a bounding box.
• count_features counts matches without returning the matching records, making it suitable for estimating result size before retrieval.
• get_usage reports account and quota information without using quota.

It also provides an Overpass QL cheat-sheet resource, a resource describing differences from public Overpass servers, and a write-bounded-overpass-query prompt.

Limitations and notes

Queries without an explicit [timeout:] receive a 25-second timeout. A query can set its own timeout up to the limit for the key’s tier. Rate and concurrency limits are determined by the Overspan key. The response-size cap may remove elements from large Overpass JSON responses; increase OVERSPAN_MAX_RESPONSE_CHARS when a larger result is necessary.

Returned data is OpenStreetMap data under the Open Database License. Published material that displays or derives from the data must include visible credit linking to OpenStreetMap’s copyright page. The Overspan subscription covers hosting and access, not the underlying data license.

The package is MIT licensed. Development commands in the repository install dependencies with npm install, build with npm run build, and run tests with npm test.