@cyanheads/openstreetmap-mcp-server

Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data via MCP. STDIO or Streamable HTTP. 6 Tools

Overview

OpenStreetMap data through Nominatim and the Overpass API. Geocode places and addresses, resolve coordinates to the nearest address, look up known OSM objects, and query features by tag around a point, inside a bounding box, or inside an OSM boundary. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Capability reference

openstreetmap_search_places tool

• Free-form query or the structured fields street, city, county, state, country, postalcode, never both; up to 40 results (limit, default 5), narrowed by countrycodes, layer, featureType, and a viewbox that biases ranking or, with bounded: true, restricts it
• Results carry coordinates, structured address, boundingbox, importance, and osm_type + osm_id; extratags adds the object's contact and physical-attribute tags; an empty first page fails as no_results
• truncated is confirmed by a same-call probe past limit, and any full page returns nextExcludeIds to pass back as exclude_place_ids; an exhausted walk returns zero results with a notice, not an error

openstreetmap_reverse_geocode tool

• lat / lon plus zoom from 3 (country) to 18 (building, the default); layer defaults to address,poi
• Returns the nearest indexed object with structured address, osm_type + osm_id, and boundingbox; coordinates with no OSM data fail as no_coverage

openstreetmap_lookup_objects tool

• Up to 50 osm_ids per call, each prefixed N, W, or R (["N240109189"]); a malformed ID fails as invalid_id_format
• Returns address records for the objects found and lists the rest under not_found

openstreetmap_query_nearby tool

• lat / lon with radius_meters up to 50,000 (default 1,000); one primary tag, amenity or tag_key with an optional tag_value, plus up to five ANDed filters; up to 500 features per page
• Features carry osm_type + osm_id, coordinates, distance_meters, and the full tag set, sorted nearest-first; effectiveTag echoes the whole filter chain

openstreetmap_query_bbox tool

• One scope per call: the corners south, west, north, east, or within and one R/W boundary ref (R237385) built from a geocoding result's osm_type + osm_id; the same tag filters and 500-per-page cap as openstreetmap_query_nearby
• effectiveArea echoes how within resolved and areasTimestamp how old the Overpass area data is; a ref that maps to no area returns an empty page whose notice names the cause
• A west greater than east is a box crossing the antimeridian; only south greater than north fails, as invalid_bbox

openstreetmap_query_raw tool

• Any Overpass QL containing [out:json], with [timeout:N] injected from timeout_seconds (up to 180, default 30) when the query has none; up to 500 elements per page
• Returns raw elements whose shape varies by type (ways carry nodes[], relations members[]), plus total_elements and the effectiveQuery as sent; malformed QL fails as query_error with the parse error Overpass reported
• max_element_bytes (default 20,000, ceiling 10,000,000) withholds an over-budget element's members, nodes, or geometry arrays whole, listed under withheld_keys; withheldElements and withheldNotice give the offset and budget that fetch it back

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

OpenStreetMap-specific:

• Nominatim request starts are spaced 1,050 ms apart to respect its one-request-per-second policy, and OSM_USER_AGENT identifies the server to both upstreams
• Overpass submissions are capped per endpoint by OSM_OVERPASS_MAX_CONCURRENCY or an entry's |N, with opt-in failover across OSM_OVERPASS_ENDPOINTS (see Overpass endpoint failover)
• The Overpass tools page with limit and offset and report totalFound, truncated, and nextOffset; a match set of up to 100,000 elements is cached for 10 minutes, so re-paging makes no new upstream request (Nominatim responses are cached for 60), and identical queries in flight at once share one submission
• Upstream rejections keep their cause: an Overpass 5xx carries its runtime error remark, a Nominatim 400 fails as invalid_parameters naming the rejected parameter
• OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL point the server at a self-hosted or mirror instance

Agent-friendly output:

• Provenance: effectiveQuery, effectiveTag, and effectiveArea echo what was sent, Overpass responses add data_timestamp and servingEndpoint, and every response carries the ODbL attribution
• Cross-tool chaining: osm_type + osm_id from any tool feed openstreetmap_lookup_objects, and a geocoded relation or way becomes a within ref for openstreetmap_query_bbox
• Tag semantics stated outright: the Nominatim tools pick objects by name, address, proximity, or ID, never by tag, and tagSelectionCaveat says so (on every openstreetmap_search_places response, and on the other two when extratags is set). Overpass filters take literal text; regex, alternation, and negation go through openstreetmap_query_raw
• Community-edited names and tag values are escaped in the Markdown surface so they cannot inject headings or formatting; structuredContent keeps the raw text

Getting started

Public Hosted Instance

A public instance is available at https://openstreetmap.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "openstreetmap-mcp-server": {
      "type": "streamable-http",
      "url": "https://openstreetmap.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "openstreetmap-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/openstreetmap-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "openstreetmap-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/openstreetmap-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "openstreetmap-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/openstreetmap-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API key. Nominatim and Overpass are public services; for heavy use, point OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL at your own instances.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/openstreetmap-mcp-server.git

1. Navigate into the directory:

cd openstreetmap-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env to override endpoints or the User-Agent as needed

Configuration

See .env.example for the full list of optional overrides. An invalid value for any OSM_* variable stops the server at startup with a message naming the variable.

Overpass endpoint failover

By default every Overpass query goes to one endpoint, the FOSSGIS-operated main instance, so a degraded endpoint fails the call. Listing more in OSM_OVERPASS_ENDPOINTS lets a failure advance to the next entry inside the same call, in list order:

OSM_OVERPASS_ENDPOINTS="https://overpass-api.de/api/interpreter,https://overpass.private.coffee/api/interpreter"

• An endpoint that throttles, answers 401/403/404/501 or a redirect, refuses the connection or fails DNS, reports an instance fault, or never answers is skipped for the rest of the call. Redirects are never followed. Any other 5xx, a 408, or a 425 stays eligible for a retry.
• A host that cannot be connected to, or stays silent through a full attempt window, is also skipped by later calls while it cools down: 30 seconds, doubling with each repeat up to 10 minutes, after which one call tries it again. Any HTTP response from it ends the cooldown. Error messages name a skipped host's last outcome with (cooling down), and when every endpoint is cooling a call still tries the one cooling longest.
• When every endpoint has refused, the call fails with their shared error if they all failed the same way (rate_limited for throttling, upstream_error for an instance fault, endpoints_rejected for an HTTP refusal such as a wrong path or a missing key), endpoints_exhausted if none answered, or endpoints_unavailable if none could be reached or they failed in a mix of ways, with each endpoint's outcome in the message.
• Endpoints are reported by origin alone (https://overpass-api.de) in servingEndpoint, error messages, and logs. Where an endpoint's own error text quotes an entry's whole path, query string, or userinfo verbatim, the server repeats each as …, so a key in the URL path or query reaches a response or a log only if the endpoint echoes it in another form, such as the key alone or re-encoded. Two entries on one origin read as (entry 1), (entry 2) by list position.
• A failure moves to an entry the call has not tried at once; a return to one it already tried waits out a backoff. One call gets a time budget of at least 120 seconds, widened by the query's [timeout:N].
• A listed mirror is failover only, so a longer list never adds queries in flight: calls run on the first entry, OSM_OVERPASS_MAX_CONCURRENCY at a time. To add capacity, size a mirror with |N — https://mirror.example/api/interpreter|4 gives it four slots of its own, and new calls take the first entry with a free slot. Write a | inside a URL as %7C.
• Calls past the slots wait in line in arrival order, for at most 30 seconds in total; a call still waiting then fails with pacer_shed and a retryAfter of at least 30 seconds.

Adding an endpoint sends your queries to a third party. Before listing one, check its usage policy on the OSM wiki instance list, confirm it holds global data (a regional instance answers a query outside its extract with an empty HTTP 200), and expect mirrors to lag the main instance; servingEndpoint and data_timestamp on every response show which host answered and how fresh its data was.

Running the server

Local development

• Build and run the production version:

```sh # One-time build bun run rebuild

# Run the built server bun run start:http # or bun run start:stdio ```

• Run checks and tests: sh bun run devcheck # Lints, formats, type-checks, and more bun run test # Runs the test suite

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/openstreetmap-mcp-server:latest

# or build locally
docker build -t openstreetmap-mcp-server .
docker run --rm -p 3010:3010 openstreetmap-mcp-server

The image serves HTTP at http://localhost:3010/mcp in stateless session mode and logs to /var/log/openstreetmap-mcp-server. OpenTelemetry peer dependencies are installed by default; build with --build-arg OTEL_ENABLED=false to omit them. Runtime telemetry stays off until you pass -e OTEL_ENABLED=true.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for logging, ctx.state for storage
• Register new tools in the createApp() arrays in src/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Map data from OpenStreetMap contributors, available under the Open Database License (ODbL).