Openstreetmap MCP Server

Official6 tools

by cyanheads · TypeScript

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

Geocode locations and query OpenStreetMap spatial data.

Topics

ai-agentbungeocodinggeolocationmcpmcp-servermodel-context-protocolnominatimopenstreetmaposmoverpassreverse-geocodingspatialtypescriptcyanheads

Captured live from the server via tools/list.

openstreetmap_geocode

Convert a place name or address to geographic coordinates and structured place data via Nominatim/OpenStreetMap. Accepts either a free-form query string (e.g., "Space Needle Seattle") or structured address fields (street, city, state, etc.) — the two modes are mutually exclusive. Returns results ordered by Nominatim relevance (importance score). Use countrycodes to restrict results to specific countries. For exhaustive POI lists in an area, use openstreetmap_query_nearby or openstreetmap_query_bbox instead — Nominatim search returns best matches, not all matching objects.

Parameters (13)

querystring
Free-form search string (e.g., "Space Needle Seattle" or "1600 Pennsylvania Ave NW, Washington DC"). Cannot be combined with structured address fields.
streetstring
House number and street name (structured query). Use with city/state/country fields. Cannot be combined with query.
citystring
City name (structured query).
countystring
County or district (structured query).
statestring
State or province (structured query).
countrystring
Country name or ISO 3166-1 alpha-2 code (structured query).
postalcodestring
Postal or ZIP code (structured query).
limitinteger
Maximum results to return. Nominatim may return fewer when additional results do not sufficiently match. Max 40.
countrycodesstring
Restrict results to one or more countries. Comma-separated ISO 3166-1 alpha-2 codes (e.g., "us,ca"). Preferred over the structured country field when filtering.
layerstring
Filter by data layer. Comma-separated values: address, poi, railway, natural, manmade. Default: no restriction.
featureTypestring
Restrict results to a geographic feature type. Automatically implies the address layer.
extratagsboolean
Include extra OSM tags when available (e.g., phone, website, opening_hours, wikidata). Increases response size.
languagestring
Preferred language for result names (BCP 47 code or Accept-Language string, e.g., "en", "de", "fr,en"). Defaults to local OSM language.

openstreetmap_reverse

Convert latitude/longitude coordinates to the nearest address or place name via Nominatim/OpenStreetMap. Returns the closest matching OSM object at the given coordinates. Note: Nominatim finds the nearest indexed OSM object — in dense areas this may differ from the address at the exact coordinate. Use zoom=18 for building-level accuracy, lower zoom values for coarser resolution (e.g., zoom=10 for city-level).

Parameters (6)

latnumberrequired
Latitude in WGS84 decimal degrees.
lonnumberrequired
Longitude in WGS84 decimal degrees.
zoominteger
Address detail level, roughly corresponding to map zoom. 18=building, 16=street, 14=neighbourhood, 12=town, 10=city, 8=county, 5=state, 3=country.
layerstring
Restrict which OSM layer is matched. Comma-separated: address, poi, railway, natural, manmade. Default: address,poi.
extratagsboolean
Include extra OSM tags when available (phone, website, opening_hours, wikidata, etc.).
languagestring
Preferred language for the result (BCP 47 code or Accept-Language string).

openstreetmap_lookup

Fetch address details for one or more known OSM objects by their IDs via Nominatim. Each ID must be prefixed with N (node), W (way), or R (relation), e.g., "N240109189", "W50637691", "R146656". Up to 50 IDs per call. Use when an OSM ID is already known from a prior openstreetmap_query_nearby or openstreetmap_query_bbox result — this is more efficient than a geocoding round trip to get the full Nominatim address record.

Parameters (3)

osm_idsanyrequired
One or more OSM IDs, each prefixed with N (node), W (way), or R (relation). E.g., "N240109189", ["W50637691", "R146656"]. Up to 50 IDs per call.
extratagsboolean
Include extra OSM tags (phone, website, wikidata, etc.).
languagestring
Preferred language for names (BCP 47 code).

openstreetmap_query_nearby

Find OSM features within a radius around a geographic point via the Overpass API. The primary tool for "what's near X?" spatial queries. Use amenity for common POI types (hospital, pharmacy, restaurant, cafe, school, atm, etc.) or tag_key + tag_value for other OSM categories (leisure=park, shop=supermarket, natural=peak). Exactly one of amenity or tag_key/tag_value must be provided. Results include all element types specified (nodes cover standalone POIs, ways cover buildings and areas), each with its full OSM tag set, sorted nearest-first by distance_meters from the center point. The extratags flag is not needed here — it applies only to the Nominatim-backed geocode/reverse/lookup tools.

Parameters (9)

latnumberrequired
Center latitude in WGS84 decimal degrees.
lonnumberrequired
Center longitude in WGS84 decimal degrees.
radius_metersnumber
Search radius in meters. Max 50,000m (50km). Keep under 5,000m for dense urban POI queries to avoid slow responses.
amenitystring
OSM amenity tag value (e.g., "hospital", "pharmacy", "restaurant", "school", "atm"). Shortcut for tag_key="amenity". Cannot be combined with tag_key/tag_value.
tag_keystring
OSM tag key for non-amenity queries (e.g., "leisure", "shop", "highway", "natural"). Use with tag_value. Cannot be combined with amenity.
tag_valuestring
OSM tag value paired with tag_key (e.g., "park", "supermarket", "primary", "peak").
element_typesarray
OSM element types to search. Ways cover most buildings and areas; nodes cover most standalone POIs. Add "relation" for complex structures like large campuses.
limitinteger
Maximum results to return. Applied after the Overpass query — if the area has more features, they are truncated.
timeout_secondsinteger
Overpass query timeout in seconds. Increase for large radius or dense areas.

openstreetmap_query_bbox

Find OSM features within a rectangular geographic area (bounding box) via the Overpass API. Useful for area surveys where you want everything in a region, not proximity searches. Use amenity for common POI types (hospital, pharmacy, cafe, school, etc.) or tag_key + tag_value for other OSM categories (leisure=park, shop=supermarket, natural=peak). Exactly one of amenity or tag_key/tag_value must be provided. Every feature includes its full OSM tag set; the extratags flag (used by geocode/reverse/lookup) does not apply here. For proximity searches centered on a point, use openstreetmap_query_nearby instead.

Parameters (10)

southnumberrequired
Southern boundary latitude (minimum latitude).
westnumberrequired
Western boundary longitude (minimum longitude).
northnumberrequired
Northern boundary latitude (maximum latitude).
eastnumberrequired
Eastern boundary longitude (maximum longitude).
amenitystring
OSM amenity tag value shortcut (e.g., "cafe", "bench", "hospital"). Cannot be combined with tag_key/tag_value.
tag_keystring
OSM tag key for non-amenity queries (e.g., "leisure", "shop", "natural"). Use with tag_value. Cannot be combined with amenity.
tag_valuestring
OSM tag value paired with tag_key (e.g., "park", "supermarket", "peak").
element_typesarray
OSM element types to search. Ways cover most buildings and areas; nodes cover most standalone POIs. Add "relation" for complex structures.
limitinteger
Maximum results to return. Applied after the Overpass query — if the area has more features, they are truncated.
timeout_secondsinteger
Overpass query timeout in seconds. Increase for large bounding boxes or dense areas.

openstreetmap_query_raw

Execute a raw Overpass QL query for advanced spatial queries that the convenience tools do not cover. Use for multi-type queries, union queries, relation membership, historical queries, or any operation requiring full Overpass QL expressiveness. The query must include [out:json]. Example: "[out:json][timeout:15];node[\"natural\"=\"peak\"](47.5,-122.5,47.7,-122.2);out body;" Validate complex queries at overpass-turbo.eu before use. For simple "what's near X?" or "what's in this area?" queries, use openstreetmap_query_nearby or openstreetmap_query_bbox instead.

Parameters (2)

querystringrequired
Overpass QL query string. Must include [out:json]. The server sets the endpoint and User-Agent; do not include those. Example: "[out:json][timeout:15];node[\"natural\"=\"peak\"](47.5,-122.5,47.7,-122.2);out body;"
timeout_secondsinteger
Query timeout in seconds. The [timeout:N] directive in the query string takes precedence if present. Max 180s.

README.md12 KBView on GitHub

<div align="center"> <h1>@cyanheads/openstreetmap-mcp-server</h1> <p><b>Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data via MCP. STDIO or Streamable HTTP.</b> <div>6 Tools</div> </p> </div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://openstreetmap.caseyjhand.com/mcp

</div>

Tools

6 tools for geocoding and spatial queries against OpenStreetMap data:

Tool	Description
`openstreetmap_geocode`	Convert a place name or address to geographic coordinates and structured place data
`openstreetmap_reverse`	Convert latitude/longitude coordinates to the nearest address or place name
`openstreetmap_lookup`	Fetch address details for one or more known OSM objects by their IDs
`openstreetmap_query_nearby`	Find OSM features within a radius around a geographic point
`openstreetmap_query_bbox`	Find OSM features within a rectangular bounding box
`openstreetmap_query_raw`	Execute a raw Overpass QL query for advanced spatial operations

`openstreetmap_geocode`

Convert a place name or address to geographic coordinates via Nominatim/OpenStreetMap.

Two input modes: free-form query string (e.g., "Space Needle Seattle") or structured address fields (street, city, state, country, postal code) — mutually exclusive
Country filtering via ISO 3166-1 alpha-2 codes (countrycodes)
Data layer filtering: address, poi, railway, natural, manmade
Feature type restriction: country, state, city, settlement
Optional extra OSM tags (phone, website, opening_hours, wikidata)
Preferred language override via BCP 47 code
Returns results ordered by Nominatim importance score (global prominence)
Results include coordinates, structured address, bounding box, OSM type/ID for chaining into openstreetmap_lookup

`openstreetmap_reverse`

Convert latitude/longitude to the nearest address or named place.

Zoom-level control for address detail: 18=building, 16=street, 14=neighbourhood, 12=town, 10=city, 8=county, 5=state, 3=country
Layer filtering for matched OSM object type
Optional extra OSM tags and language preference
Returns structured address breakdown, OSM type/ID, and bounding box

`openstreetmap_lookup`

Fetch full Nominatim address records for known OSM object IDs.

Accepts single ID or array of up to 50 IDs
IDs must be prefixed with N (node), W (way), or R (relation): e.g., "N240109189", "W50637691", "R146656"
Efficient alternative to a full geocoding round-trip when OSM IDs are already known (e.g., from an Overpass result)
Reports not_found list for IDs that returned no result
Optional extra OSM tags and language preference

`openstreetmap_query_nearby`

Find OSM features within a radius around a point via the Overpass API.

Primary tool for "what's near X?" spatial queries
Supports amenity shortcut for common POI types (hospital, pharmacy, restaurant, cafe, school, atm) or tag_key + tag_value for any OSM category (leisure=park, shop=supermarket, natural=peak)
Configurable radius up to 50km; keep under 5km for dense urban POI queries
Element type filtering: node (standalone POIs), way (buildings/areas), relation (complex structures)
Limit up to 500 results; truncated flag signals when more exist
Returns OSM type/ID, coordinates, name, and full tag set for each feature

`openstreetmap_query_bbox`

Find OSM features within a rectangular geographic bounding box.

Useful for area surveys where proximity to a single point isn't the goal
Same amenity / tag_key + tag_value interface as openstreetmap_query_nearby
Configurable timeout for large bounding boxes or dense areas
Limit up to 500 results with truncated flag

`openstreetmap_query_raw`

Execute arbitrary Overpass QL for queries the convenience tools don't cover.

Full Overpass QL expressiveness: multi-type queries, union queries, relation membership, historical queries
Query must include [out:json]; server injects [timeout:N] if absent
Returns raw element array — structure varies by query type (nodes have lat/lon, ways have nodes[], relations have members[])
Validate complex queries at overpass-turbo.eu before use

Features

Built on @cyanheads/mcp-ts-core:

Declarative tool definitions — single file per tool, framework handles registration and validation
Unified error handling across all tools
Pluggable auth (none, jwt, oauth)
Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
Structured logging with optional OpenTelemetry tracing
Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

Nominatim/Overpass-specific:

Nominatim usage policy compliance: configurable User-Agent via OSM_USER_AGENT, rate-limit-aware request handling
OSM attribution on every response (Data © OpenStreetMap contributors, ODbL 1.0)
Private instance support — override OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL for self-hosted or mirror endpoints
Structured error contracts: no_results, no_coverage, invalid_id_format, invalid_tag, query_timeout, rate_limited, query_error, result_too_large — all with actionable recovery hints

Agent-friendly output:

Attribution on every response — agents can surface the ODbL license notice as required
Structured output contracts — coordinates, OSM IDs, address fields, and tag maps in consistent shapes
Cross-tool chaining: Overpass results carry osm_type + osm_id that feed directly into openstreetmap_lookup for full address records

Getting started

Self-Hosted / Local

Add the following to your MCP client configuration file.

json

{
  "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):

json

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

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.3.0 or higher (or Node.js ≥24.0.0).
No API key required — Nominatim and Overpass are public APIs. For heavy use, consider pointing OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL at self-hosted or mirror instances.

Installation

Clone the repository:

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

Navigate into the directory:

cd openstreetmap-mcp-server

Install dependencies:

bun install

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

Variable	Description	Default
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`	`stdio`
`MCP_HTTP_PORT`	HTTP server port	`3010`
`MCP_HTTP_ENDPOINT_PATH`	HTTP endpoint path where the MCP server is mounted	`/mcp`
`MCP_PUBLIC_URL`	Public origin override for TLS-terminating reverse-proxy deployments	none
`MCP_AUTH_MODE`	Authentication: `none`, `jwt`, or `oauth`	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `warning`, `error`, etc.)	`info`
`MCP_GC_PRESSURE_INTERVAL_MS`	Opt-in Bun-only forced-GC pressure loop (ms). Recommended starting point if heap growth is observed: `60000`.	`0` (disabled)
`STORAGE_PROVIDER_TYPE`	Storage backend: `in-memory`, `filesystem`, `supabase`, `cloudflare-kv/r2/d1`	`in-memory`
`OSM_NOMINATIM_BASE_URL`	Nominatim API base URL. Override for a private or mirror instance.	`https://nominatim.openstreetmap.org`
`OSM_OVERPASS_BASE_URL`	Overpass API endpoint URL. Override for a mirror or private instance.	`https://overpass-api.de/api/interpreter`
`OSM_USER_AGENT`	User-Agent sent to Nominatim and Overpass. Required by usage policy.	`openstreetmap-mcp-server/<package version>`
`OTEL_ENABLED`	Enable OpenTelemetry	`false`

Running the server

Local development

Build and run the production version:

# One-time build
bun run rebuild

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

Run checks and tests:

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

Project structure

Directory	Purpose
`src/mcp-server/tools`	Tool definitions (`*.tool.ts`). Six tools across Nominatim and Overpass.
`src/services/nominatim`	Nominatim service layer — API client, search, reverse, lookup.
`src/services/overpass`	Overpass service layer — query builder, executor, element normalizer.
`src/config`	Server-specific environment variable parsing and validation with Zod.

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 and resources in the createApp() arrays

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

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

Install

Tools (6)

openstreetmap_geocodeopenstreetmap_reverseopenstreetmap_lookupopenstreetmap_query_nearbyopenstreetmap_query_bboxopenstreetmap_query_raw

Configuration

Environment variables

OSM_NOMINATIM_BASE_URLdefault https://nominatim.openstreetmap.org

Nominatim API base URL. Override to use a private or mirror instance.

OSM_USER_AGENTdefault openstreetmap-mcp-server/0.2.10

User-Agent sent to Nominatim and Overpass. Required by usage policy.

OSM_OVERPASS_BASE_URLdefault https://overpass-api.de/api/interpreter

Overpass API endpoint URL. Override to use a mirror or private instance.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_PUBLIC_URL

Public origin override for deployments behind a TLS-terminating reverse proxy (e.g. https://mcp.example.com).

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "openstreetmap-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/openstreetmap-mcp-server@0.2.10",
        "run",
        "start:stdio"
      ],
      "env": {
        "OSM_NOMINATIM_BASE_URL": "https://nominatim.openstreetmap.org",
        "OSM_USER_AGENT": "openstreetmap-mcp-server/0.2.10",
        "OSM_OVERPASS_BASE_URL": "https://overpass-api.de/api/interpreter",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

GitHub

Stars: 2
Forks: 0
Open issues: 3
Language: TypeScript
License: Apache License 2.0
Default branch: main
Latest release: v0.2.10 · 7/5/2026
Created: 5/23/2026
Updated: 7/5/2026

Trust grades

License: A
Maintenance: A
Quality: Not tested yet

Graded A-F from license permissiveness and commit recency; a cross-model quality score is coming soon.

npm

Package: @cyanheads/openstreetmap-mcp-server
Downloads/mo: 1,411
Latest version: 0.2.10
Published: 7/5/2026

Details

Name: io.github.cyanheads/openstreetmap-mcp-server
Version: 0.2.10
Status: active
Published: 7/5/2026
Updated: 7/5/2026
Official: Yes
Homepage: www.npmjs.com/package/@cyanhe…
Repository: cyanheads/openstreetmap-mcp-server
Registry record: View server.json

Connect agentage Memory

The cross-vendor memory every AI reads and writes - Claude, Cursor, ChatGPT - mirrored as plain markdown files you own and can export anytime.

MCP endpointmemory.agentage.io/mcp

Connect Memory

One memory. Every AI. Owned by you.