English Français العربية

dev.overspan/mcp

Official registry Other

OpenStreetMap queries as MCP tools, served by the Overspan hosted Overpass API.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package overspan-mcp
Claude Code 
claude mcp add dev-overspan-mcp -e 'OVERSPAN_API_KEY=<your overspan_api_key>' -- npx -y overspan-mcp@0.1.2
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "dev-overspan-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "overspan-mcp@0.1.2"
            ],
            "env": {
                "OVERSPAN_API_KEY": "<your overspan_api_key>"
            }
        }
    }
}

Environment variables

  • OVERSPAN_API_KEY required secret Overspan API key, sent as an Authorization: Bearer header. Plans at https://overspan.dev/#pricing; the key arrives by email after checkout.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. overspan-mcp
  2. Quickstart
  3. Tools
  4. Behaviour worth knowing
  5. Environment variables
  6. Data licence
  7. Development
  8. Links

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

ToolWhat it does
overpass_queryRun a raw Overpass QL query. The escape hatch when the helpers are too narrow.
find_nearbyFeatures matching tag filters within a radius of a point.
features_in_bboxFeatures matching tag filters inside a bounding box.
count_featuresCount matches in an area without returning them. Cheap; use it before pulling data.
get_usageThe 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: Bearer header, 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_usage gives 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_CHARS if you want more.
  • Queries without [timeout:] get 25 seconds. Set it explicitly for heavy queries, up to your tier's cap.

Environment variables

VariableRequiredDefaultPurpose
OVERSPAN_API_KEYyesYour Overspan API key
OVERSPAN_API_URLnohttps://api.overspan.devOverride the API endpoint
OVERSPAN_MAX_RESPONSE_CHARSno48000Truncation 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.

Overspan is an independent service, not affiliated with the OpenStreetMap Foundation or the Overpass API project.

MIT licensed.

Frequently asked questions

What is dev.overspan/mcp?

OpenStreetMap queries as MCP tools, served by the Overspan hosted Overpass API.

How do I install dev.overspan/mcp?

It runs on your machine. In Claude Code: claude mcp add dev-overspan-mcp -e 'OVERSPAN_API_KEY=<your overspan_api_key>' -- npx -y overspan-mcp@0.1.2. For other clients, paste the JSON configuration from this page into their MCP settings.

Does dev.overspan/mcp need an API key?

Yes. It expects OVERSPAN_API_KEY, which you set in its configuration.

Is dev.overspan/mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains dev.overspan/mcp?

It is published by julesmaxxx. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.