Openstreetmap Mcp Server

io.github.cyanheadsPublished by GitHub account cyanheadsv0.7.1Updated Nov 5, 2026

Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.

VerifiedStreamable HTTPWeb executableDatabasesLocation & Lifestyle

Overview

AI-generated overview

OpenStreetMap geocoding and Overpass spatial query server: turn place names into coordinates, coordinates into addresses, and survey OSM features by tag.

What you can do
  • Geocode place names or structured addresses to coordinates, and reverse geocode coordinates to the nearest address or named place
  • Look up full address records for known OSM object IDs
  • Find OSM features within a radius of a point, filtered by amenity or tag key and value
  • Survey features inside a bounding box or inside an OSM boundary such as a city or park
  • Run arbitrary Overpass QL queries for unions, relation membership, regex tags or historical data
When to use it
Useful when an assistant needs real-world place data: resolving addresses to coordinates, describing what is near a location, or listing features inside an area for mapping, travel or local research tasks.
Requirements
Either the hosted HTTP endpoint or a local process via npx (Node.js) or Bun for a source build. No API key is required. Optional variables set the Nominatim and Overpass endpoints, Overpass concurrency and failover, and OSM_USER_AGENT, which the usage policy requires. Network access to Nominatim and Overpass is needed.
Before you install
Queries go to public Nominatim and Overpass instances with rate limits, so heavy use should point OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL at your own instances. Adding entries to OSM_OVERPASS_ENDPOINTS sends your queries to third parties whose policies and data freshness you should check. The tools are read-only and return OpenStreetMap data under ODbL 1.0, which requires attribution.

Installation

In SourceWeft

  1. Open Openstreetmap Mcp Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.cyanheads%2Fopenstreetmap-mcp-server/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

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

README

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

Tools

ToolDescription
openstreetmap_search_placesConvert a place name or address to coordinates and structured place data
openstreetmap_reverse_geocodeConvert latitude/longitude to the nearest address or place name
openstreetmap_lookup_objectsFetch address records for known OSM objects by ID
openstreetmap_query_nearbyFind OSM features within a radius of a point
openstreetmap_query_bboxFind OSM features inside a bounding box or an OSM boundary such as a city, park, or region
openstreetmap_query_rawRun a raw Overpass QL query for anything the other tools cannot express

Capability reference

The openstreetmap-guide skill covers place resolution, spatial queries, paging, and interpreting coverage and tag results.

Argument aliases are accepted before canonical validation: latitude / longitude for lat / lon on nearby and reverse queries, radius_m for nearby's radius_meters, and q for search's query. Send either spelling, never both. radius, tag, and tags remain invalid; advertised schemas use canonical names.

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; a larger limit is served as 40 with a limitNotice), narrowed by countrycodes, layer, featureType, and a viewbox (restricting with bounded: true)
  • Results carry coordinates, structured address, boundingbox, importance, and osm_type + osm_id; extratags adds contact and physical-attribute tags; an empty first page fails as no_results, naming any countrycodes, layer, featureType, or bounded viewbox that was sent
  • Every page with results returns nextExcludeIds to pass back as exclude_place_ids, since a page shorter than limit can still have more; once results run out you get zero results and a notice, not an error, and a walk too long for the instance's URL limit fails as request_too_long

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 500 osm_ids entries, each prefixed N, W, or R (["N240109189"]); a malformed ID fails as invalid_id_format
  • The first 50 unique IDs are looked up; the rest come back as deferred_ids for the next call
  • Returns address records for the objects found and lists the rest under not_found (including objects Nominatim does not index, such as street lamps); a notice carries an openstreetmap_query_raw query to check which exist

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 (a larger limit is served as 500 with a limitNotice)
  • element_types searches nodes, ways, and relations unless set; ["node", "way"] leaves relations out
  • A value matches exactly by default; list_item mode (tag_value_match, or match on a filter) matches one item of a semicolon list, so cuisine = pizza also finds cuisine=pizza;italian
  • An amenity value that OpenStreetMap tags under another key (amenity: "museum"; museums are tourism=museum) gets a notice naming the key to retry with
  • Features carry osm_type + osm_id, coordinates, distance_meters (to the feature's nearest point), and the full tag set, sorted nearest-first; effectiveTag echoes the filter chain
  • With ways or relations searched, an area containing the point, such as the park or city it lies in, matches at distance_meters 0 whatever the radius, and areasTimestamp says how old the area data is. An endpoint that cannot run the area lookup is asked again without it, and the notice says areas containing the point were not checked

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, list-item matching, stray-amenity notice, and 500-per-page cap as openstreetmap_query_nearby
  • element_types searches nodes, ways, and relations unless set; ["node", "way"] leaves relations out
  • effectiveArea names the boundary within reached by its name, boundary, and admin_level tags, then the Overpass area it mapped to, so a mistyped ref shows; areasTimestamp says how old the area data is; a ref that maps to no area returns an empty page with a notice
  • A west greater than east is a box crossing the antimeridian; south greater than north fails as invalid_bbox

openstreetmap_query_raw tool

  • Any Overpass QL containing [out:json]; [timeout:N] comes from timeout_seconds (up to 180, default 30) and [maxsize:268435456] (256 MiB) is added when the query sets none; up to 500 elements per page (a larger limit is served as 500 with a limitNotice)
  • Returns raw elements (ways carry nodes[], relations members[]), plus total_elements and the effectiveQuery as sent; malformed QL fails as query_error with Overpass's parse error
  • max_element_bytes (default 20,000, minimum 1,000) withholds an over-budget element's members, nodes, or geometry arrays, listed under withheld_keys; withheldElements and withheldNotice say how to fetch them

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 requests are spaced 1,050 ms apart to respect its one-request-per-second policy; OSM_USER_AGENT identifies the server to both upstreams
  • Overpass queries are limited per endpoint by OSM_OVERPASS_MAX_CONCURRENCY, with opt-in failover across OSM_OVERPASS_ENDPOINTS (see Overpass endpoint failover)
  • Overpass tools page with limit and offset and report totalFound, truncated, and nextOffset; results are cached for 10 minutes (Nominatim for 60), so re-paging makes no new upstream request
  • An Overpass response over 64 MiB fails as result_too_large
  • OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL point the server at a self-hosted or mirror instance

Agent-friendly output:

  • effectiveQuery and effectiveTag echo what was sent, and effectiveArea names the boundary a within ref reached; Overpass responses add data_timestamp and servingEndpoint, and every response carries the ODbL attribution
  • 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
  • The Nominatim tools never select by tag, and tagSelectionCaveat says so; regex, alternation, and negation go through openstreetmap_query_raw
  • Names and tag values are escaped in the Markdown output; structuredContent keeps the raw text

Getting started

Connect to the hosted instance, no install:

sh
claude mcp add --transport http openstreetmap-mcp-server https://openstreetmap.caseyjhand.com/mcp

Or run it locally:

sh
claude mcp add openstreetmap-mcp-server -- npx -y @cyanheads/openstreetmap-mcp-server

For other clients, add this to the MCP config file:

json
{  "mcpServers": {    "openstreetmap-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/openstreetmap-mcp-server"]    }  }}

No API key is required. For heavy use, point OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL at your own instances. For Docker or a source build, see Running the server.

Configuration

VariableDescriptionDefault
OSM_NOMINATIM_BASE_URLNominatim base URL. A path prefix such as https://maps.example.com/nominatim is supported.https://nominatim.openstreetmap.org
OSM_OVERPASS_BASE_URLPins every query to one Overpass endpoint and disables failover.unset
OSM_OVERPASS_ENDPOINTSComma-separated, ordered Overpass endpoints; more than one enables failover. Ignored when OSM_OVERPASS_BASE_URL is set.https://overpass-api.de/api/interpreter
OSM_OVERPASS_MAX_CONCURRENCYMax Overpass queries in flight per endpoint. Public instances allow one per user.1
OSM_USER_AGENTUser-Agent sent to Nominatim and Overpass. Required by usage policy.openstreetmap-mcp-server/<package version>
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTHTTP server port.3010
MCP_SESSION_MODEHTTP session mode: stateless, stateful, or auto. The server declares stateless in code; an explicit value overrides it.stateless
MCP_AUTH_MODEAuthentication: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, warning, error, etc.).info
STORAGE_PROVIDER_TYPEStorage backend: in-memory, filesystem, supabase, cloudflare-kv/r2/d1.in-memory
OTEL_ENABLEDEnable OpenTelemetry.false

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. List more in OSM_OVERPASS_ENDPOINTS and a failed call moves to the next entry in order:

sh
OSM_OVERPASS_ENDPOINTS="https://overpass-api.de/api/interpreter,https://overpass.private.coffee/api/interpreter"
  • Endpoints that fail repeatedly are skipped for a while (30 seconds, doubling up to 10 minutes)
  • When every endpoint fails, the call fails with rate_limited, upstream_error, overpass_unavailable, endpoints_rejected, endpoints_exhausted, or endpoints_unavailable, with each endpoint's outcome in the message
  • Endpoints are reported by origin only (https://overpass-api.de) in servingEndpoint, error messages, and logs
  • Extra entries are failover only and never add concurrency. For an instance that allows parallel queries, append |N to its entry (https://mirror.example/api/interpreter|4) for N slots; write a literal | in a URL as %7C. Never size a public instance (the FOSSGIS servers, maps.mail.ru, overpass.private.coffee)
  • Calls waiting for a slot fail with pacer_shed and a retryAfter of at least 30 seconds after 30 seconds in line

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

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

sh
git clone https://github.com/cyanheads/openstreetmap-mcp-server.gitcd openstreetmap-mcp-server && bun installcp .env.example .env# edit .env to override endpoints or the User-Agent as needed

  • Build and run the production version:

    sh
    # One-time buildbun run rebuild
# Run the built serverbun run start:http# orbun run start:stdio

  • Run checks and tests:

    sh
    bun run devcheck  # Lints, formats, type-checks, and morebun run test      # Runs the test suite

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/openstreetmap-mcp-server:latest
# or build locallydocker 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

DirectoryPurpose
src/mcp-server/toolsTool definitions (*.tool.ts) and shared input, formatting, and escaping helpers. Six tools across Nominatim and Overpass.
src/services/nominatimNominatim service: paced API client for search, reverse, and lookup, plus error parsing.
src/services/overpassOverpass service: query builder, endpoint failover and executor, element normalizer, error parsing.
src/configServer-specific environment variable parsing and validation with Zod.
tests/Unit and integration tests for tools, services, and security.

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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

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

Source: README.md at commit 02efff6

Tools

6

openstreetmap_search_places

Geocode a place name or address

Geocode a place name or address to coordinates and structured place data via Nominatim. Send either a free-form query or the structured address fields (street, city, county, state, country, postalcode), never both; results are the best-ranked matches, not every matching object, and matching never uses an OSM attribute tag, so filter or enumerate by tag with openstreetmap_query_nearby, openstreetmap_query_bbox, or openstreetmap_query_raw.

Parameterscitylayerlimitquerystatecountystreetboundedcountryviewboxlanguageextratags+4 more

openstreetmap_reverse_geocode

Reverse geocode coordinates to an address

Convert a latitude/longitude pair to the nearest address or named place via Nominatim. The result is the closest indexed OSM object at the requested zoom (18 building, 10 city), which in dense areas can be a neighbouring feature rather than the one containing the coordinate; proximity and layer pick it, never an OSM attribute tag, so find features by tag with openstreetmap_query_nearby, openstreetmap_query_bbox, or openstreetmap_query_raw.

Parameterslatrequiredlonrequiredzoomlayerlanguageextratags

openstreetmap_lookup_objects

Look up address details for OSM objects by ID

Fetch the Nominatim address record for known OSM objects by ID, 50 per call with any more returned under deferred_ids, each prefixed N (node), W (way), or R (relation), e.g. "N240109189". Use it for IDs already in hand from openstreetmap_query_nearby or openstreetmap_query_bbox; it returns only objects named in osm_ids and lists those with no Nominatim record under not_found (Nominatim skips unnamed and non-place objects, so such an ID may still exist). It cannot select by tag, so discover objects with those tools or openstreetmap_query_raw first.

Parametersosm_idsrequiredlanguageextratags

openstreetmap_query_nearby

Find OSM features near a point

Find OSM features within a radius of a point via the Overpass API, the tool for "what is near X?" questions. Filter with amenity, or with tag_key plus an optional tag_value, ANDing up to five more filters; every feature returns with its full OSM tag set (no extratags flag here), sorted nearest-first by distance_meters. An area containing the point, such as the park or city it lies in, matches at 0 m whatever the radius.

Parameterslatrequiredlonrequiredlimitoffsetamenityfilterstag_keytag_valueelement_typesradius_meterstag_value_matchtimeout_seconds

openstreetmap_query_bbox

Find OSM features inside a bounding box or an OSM boundary

Find OSM features inside an area via the Overpass API, for surveys of everything in a region (openstreetmap_query_nearby covers proximity to a point). Scope with the four corner fields south, west, north, east, or with within and a single OSM boundary ref such as a city relation or a park way, which searches the boundary polygon itself instead of an overcovering box; never both. Filter with amenity, or with tag_key plus an optional tag_value, ANDing up to five more filters; every feature returns with its full OSM tag set (no extratags flag here).

Parameterseastwestlimitnorthsouthoffsetwithinamenityfilterstag_keytag_valueelement_types+2 more

openstreetmap_query_raw

Execute a raw Overpass QL query

Run an arbitrary Overpass QL query for anything the convenience tools cannot express: multi-type or union queries, relation membership, historical queries, regex tag matching. The query must include [out:json], e.g. "[out:json][timeout:15];node[\"natural\"=\"peak\"](47.5,-122.5,47.7,-122.2);out body;"; scope to an OSM boundary with rel(<id>);map_to_area->.a; or way(<id>);map_to_area->.a; then (area.a) on each statement (the 2400000000 way-area offset is gone since Overpass 0.7.57; openstreetmap_query_bbox takes the same scope as within, without QL). The response is one page: page with limit and offset, read totalFound and truncated for the whole match, and an element over max_element_bytes arrives with its members, nodes or geometry array withheld whole and withheldNotice saying how to fetch it back. For plain "near X" or "in this area" questions use openstreetmap_query_nearby or openstreetmap_query_bbox.

Parameterslimitqueryrequiredoffsettimeout_secondsmax_element_bytes

Version history

9
  1. v0.7.1LatestNov 5, 2026
  2. v0.7.0Oct 26, 2026
  3. v0.6.2Oct 25, 2026
  4. v0.6.1Oct 15, 2026
  5. v0.6.0Oct 3, 2026
  6. v0.5.2Sep 22, 2026
  7. v0.5.1Sep 17, 2026
  8. v0.5.0Sep 17, 2026
  9. v0.4.8Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts