# julesmaxxx/overspan-mcp [Health: Active]

**Category:** 🗺️ Location Services  
**Repository:** https://github.com/julesmaxxx/overspan-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 188  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mcp-243

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

## Tools
Capabilities this server exposes over MCP:

- **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.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "overspan-mcp": {
    "command": "npx",
    "args": ["-y","overspan-mcp"],
    "env": {
      "OVERSPAN_API_KEY": "",
      "OVERSPAN_API_URL": "",
      "OVERSPAN_MAX_RESPONSE_CHARS": ""
    }
  }
}
```

**Requires environment variables:** `OVERSPAN_API_KEY`, `OVERSPAN_API_URL`, `OVERSPAN_MAX_RESPONSE_CHARS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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`.

_Full upstream README: https://allmcps.com/mcp/mcp-243/readme_