openstreetmap-mcp-server

<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">

[![Version](https://img.shields.io/badge/Version-0.5.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/openstreetmap-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/openstreetmap-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/openstreetmap-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0%2B-blueviolet.svg?style=flat-square)](https://bun.sh/)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/openstreetmap-mcp-server/releases/latest/download/openstreetmap-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=openstreetmap-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvb3BlbnN0cmVldG1hcC1tY3Atc2VydmVyIl19) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22openstreetmap-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fopenstreetmap-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://openstreetmap.caseyjhand.com/mcp](https://openstreetmap.caseyjhand.com/mcp)

</div>

---

## Overview

Geocoding, reverse geocoding, and spatial queries over OpenStreetMap data via Nominatim and the Overpass API. Search places, resolve coordinates to addresses, and query nearby or bounded features by tag from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

### Tools

| Tool | Description |
|:---|:---|
| `openstreetmap_search_places` | Convert a place name or address to geographic coordinates and structured place data |
| `openstreetmap_reverse_geocode` | Convert latitude/longitude coordinates to the nearest address or place name |
| `openstreetmap_lookup_objects` | 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 inside a rectangular bounding box, or inside a named OSM boundary — a city, park, or region |
| `openstreetmap_query_raw` | Execute a raw Overpass QL query for advanced spatial operations |

## Capability reference

### `openstreetmap_search_places` <sub>tool</sub>

- Two input modes: free-form `query` or structured address fields (`street`, `city`, `county`, `state`, `country`, `postalcode`), mutually exclusive; `countrycodes` (ISO 3166-1 alpha-2) and `layer` (address, poi, railway, natural, manmade) narrow results, `featureType` restricts to country/state/city/settlement
- `viewbox` (west/south/east/north) biases results, or with `bounded: true` hard-restricts to the area — finer-grained than `countrycodes`, cannot cross the antimeridian; the effective box and restriction mode are echoed back
- Up to 40 results (`limit`), ordered by Nominatim importance score; `extratags` adds contact/metadata and physical-attribute tags on the matched object, `language` sets a BCP 47 preferred language
- Confirmed truncation via a same-call probe one result past `limit`; a full page carries `nextExcludeIds` to page toward further matches with `exclude_place_ids`
- Results carry coordinates, structured address, bounding box, and OSM type/ID for chaining into `openstreetmap_lookup_objects`
- Matches on name and address relevance only — `extratags` decorates the matched object but never selects it; use the Overpass tools to filter or enumerate by tag

---

### `openstreetmap_reverse_geocode` <sub>tool</sub>

- 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 the matched OSM object type
- Optional extra OSM tags (contact, metadata, physical attributes) and language preference
- Returns structured address breakdown, OSM type/ID, and bounding box
- Matches on proximity and layer, never on an OSM attribute tag — `extratags` decorates the matched object and cannot select one

---

### `openstreetmap_lookup_objects` <sub>tool</sub>

- Accepts an array of up to 50 IDs, each prefixed N (node), W (way), or R (relation), e.g. `["N240109189"]`; a single ID is still wrapped in an array
- Efficient alternative to a full geocoding round-trip when OSM IDs are already known (e.g., from an Overpass result)
- Reports a `not_found` list for IDs that returned no result
- Optional extra OSM tags (contact, metadata, physical attributes) and language preference
- Returns exactly the objects named in `osm_ids` — `extratags` decorates them and cannot select them; discover objects by tag with the Overpass tools, then pass their IDs here

---

### `openstreetmap_query_nearby` <sub>tool</sub>

- Primary tool for "what's near X?" spatial queries; the `amenity` shortcut covers common POI types (hospital, pharmacy, restaurant, cafe, school, atm), or use `tag_key` with an optional `tag_value` for other categories — omit `tag_value` to match any feature carrying that key
- Up to five additional `filters: [{ key, value? }]`, ANDed with the primary tag in input order; blank values and duplicate keys are rejected, and tags must be literal text without Overpass QL metacharacters (`"`, `\`, `[`, `]`, `;`, `(`, `)`) — use `openstreetmap_query_raw` for regex, alternation, or negation
- `effectiveTag` echoes the complete filter chain on every response
- Configurable `radius_meters` up to 50km (keep under 5km for dense urban POI queries); `element_types` filters node/way/relation
- Up to 500 results (`limit`) with offset paging and a `truncated` flag
- Returns OSM type/ID, coordinates, name, distance from the center point, and full tag set per feature, sorted nearest-first

---

### `openstreetmap_query_bbox` <sub>tool</sub>

- Useful for area surveys where proximity to a single point isn't the goal
- Two scopes, one per call: the four corner fields, or `within` — a single OSM boundary ref (`R237385` for Seattle, `W13800188` for a park), which is the `osm_type` plus `osm_id` the geocoding tools already return
- A boundary scopes to the boundary itself, where its bounding box overcovers with water and neighbouring places; `effectiveArea` echoes how the ref resolved and `areasTimestamp` reports how stale the Overpass area database is
- A ref that maps to no Overpass area — a nonexistent id, an unclosed way, a relation without an area-forming tag — returns an empty page whose notice names that cause, rather than a bare zero
- Same primary tag, key-existence, and bounded `filters` interface as `openstreetmap_query_nearby`, including trimming, blank-value, and duplicate-key validation
- A `west` greater than `east` is a box crossing the antimeridian, covering `west..180` plus `-180..east`; only `south` greater than `north` is rejected
- Configurable timeout for large bounding boxes or dense areas
- Up to 500 results (`limit`) with a `truncated` flag

---

### `openstreetmap_query_raw` <sub>tool</sub>

- Full Overpass QL expressiveness — multi-type queries, union queries, relation membership, historical queries; the query must include `[out:json]`, and the server injects `[timeout:N]` if absent
- Returns a raw element array — structure varies by query type (nodes carry lat/lon, ways carry `nodes[]`, relations carry `members[]`)
- Up to 500 elements per call (`limit`) with `totalFound`/`truncated`/`nextOffset` disclosure; page the rest with `offset`
- Per-element `max_element_bytes` budget (default 20000 UTF-8 bytes, ceiling 10000000) withholds an over-budget element's `members`/`nodes`/`geometry` arrays whole rather than truncating them, listed under `withheld_keys`
- `withheldElements`/`withheldNotice` give the one-call retrieval path for a withheld element — the same query with `limit: 1`, that element's offset, and a raised `max_element_bytes`
- `timeout_seconds` up to 180 is honored client-side; validate complex queries at [overpass-turbo.eu](https://overpass-turbo.eu) before use

## Features

Built on [`@cyanheads/mcp-ts-core`](https://github.com/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:

- Configurable `OSM_USER_AGENT` and rate-limit-aware request handling honor Nominatim's usage policy
- Overpass slot budget respected client-side via `OSM_OVERPASS_MAX_CONCURRENCY`; a throttled endpoint is never re-submitted to — the call advances to the next endpoint instead
- Opt-in Overpass endpoint failover via `OSM_OVERPASS_ENDPOINTS` — a failure advances to the next mirror inside the same call, and every response reports the endpoint that served it
- Private instance support