osm-mcp

# osm-mcp

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/osm-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/osm-mcp/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/osm-mcp)](https://www.npmjs.com/package/osm-mcp)
[![npm downloads](https://img.shields.io/npm/dm/osm-mcp)](https://www.npmjs.com/package/osm-mcp)
[![node](https://img.shields.io/node/v/osm-mcp)](https://nodejs.org)
[![Container](https://img.shields.io/badge/ghcr.io-ni--c%2Fosm--mcp-2496ED?logo=docker&logoColor=white)](https://github.com/ni-c/osm-mcp/pkgs/container/osm-mcp)
[![license](https://img.shields.io/npm/l/osm-mcp)](LICENSE)
[![Docs](https://img.shields.io/badge/docs-osm--mcp.ni--c.de-4f46e5)](https://osm-mcp.ni-c.de)

An [MCP](https://modelcontextprotocol.io) server for
[OpenStreetMap](https://www.openstreetmap.org): geocoding, walking/driving/cycling
distances and durations, multi-stop route optimization, isochrones and POI
search — built for travel planning with AI assistants.

11 tools, all read-only. All backends are free public OpenStreetMap services;
**no API key is required**. An OpenRouteService key can be supplied optionally to
switch the routing engine.

📖 **Full documentation: <https://osm-mcp.ni-c.de>**

<!-- <picture> is resolved against the colour scheme of the page showing it, so GitHub
     picks the variant that matches its own theme toggle. npm strips <picture> and
     <source> when it sanitises the README and keeps the <img>, which is why that
     fallback brings its own dark card instead of relying on a media query. -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://osm-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://osm-mcp.ni-c.de/architecture-light.svg">
  <img src="https://osm-mcp.ni-c.de/architecture.svg" alt="An MCP client talks to osm-mcp over stdio; the server exposes eleven read-only tools with rate limiting and caching, and calls Nominatim, Photon, OSRM, Valhalla and Overpass over HTTPS — plus OpenRouteService optionally with an API key" width="800">
</picture>

<img src="https://osm-mcp.ni-c.de/demo.gif" alt="Terminal recording: the server reports eleven tools, geocodes the Porta Nigra in Trier, and returns a walking route with distance and duration" width="800">

## Why another OSM MCP server?

- **Correct walking/cycling routes.** The public OSRM demo servers ignore the
  profile segment inside the OSRM URL path and always return **car** routes
  unless the FOSSGIS `routed-foot` / `routed-bike` / `routed-car` path prefixes
  are used. Most existing OSM MCP servers get this wrong and silently return
  driving times for walking queries. This server uses the prefixes and its live
  smoke test asserts that foot routes are much slower than car routes.
- **Policy-compliant by construction.** Per-service rate limiting (Nominatim and
  OSRM: 1 request/second), an identifying User-Agent on every request (required
  by the Nominatim usage policy), response caching, capped Overpass concurrency
  (2 slots) and automatic failover to an Overpass mirror on 429/5xx.
- **Photon support.** Optional typo-tolerant geocoding via komoot's Photon,
  which is designed for interactive use — a better fit for LLM-driven lookups
  than hammering Nominatim.

## Requirements

- Node.js ≥ 22
- Internet access to the public OpenStreetMap services (see table below)

## Configuration

Every variable is optional — the server works out of the box.

| Variable             | Default                                                                                   | Description                                                                                                                                                                                    |
| -------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OSM_USER_AGENT`     | `osm-mcp/<version> (+https://github.com/ni-c/osm-mcp)`                                    | User-Agent sent to every service. Nominatim requires a real, identifying one.                                                                                                                  |
| `NOMINATIM_BASE_URL` | `https://nominatim.openstreetmap.org`                                                     | Geocoding / reverse geocoding                                                                                                                                                                  |
| `PHOTON_BASE_URL`    | `https://photon.komoot.io`                                                                | Typo-tolerant geocoding                                                                                                                                                                        |
| `OSRM_BASE_URL`      | `https://routing.openstreetmap.de`                                                        | Routing, matrices, trip optimization. Must serve the `routed-{car,bike,foot}` path prefixes (the FOSSGIS layout).                                                                              |
| `OVERPASS_BASE_URL`  | `https://overpass-api.de/api/interpreter,https://overpass.private.coffee/api/interpreter` | Comma-separated Overpass endpoints, tried in order on 429/5xx                                                                                                                                  |
| `VALHALLA_BASE_URL`  | `https://valhalla1.openstreetmap.de`                                                      | Isochrones                                                                                                                                                                                     |
| `ORS_API_KEY`        | –                                                                                         | Optional [OpenRouteService](https://openrouteservice.org) key (secret). When set, routes, matrices and isochrones use ORS instead of OSRM/Valhalla. Free tier: 2000 directions/day, 40/minute. |
| `ORS_BASE_URL`       | `https://api.openrouteservice.org`                                                        | OpenRouteService endpoint                                                                                                                                                                      |
| `OSM_CACHE_TTL`      | `3600`                                                                                    | Seconds identical upstream responses are served from the in-memory cache (`0` disables caching)                                                                                                |

## Install

```sh
claude mcp add osm -- npx -y osm-mcp
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "osm": {
      "command": "npx",
      "args": ["-y", "osm-mcp"]
    }
  }
}
```

Codex (`~/.codex/config.toml`):

```toml
[mcp_servers.osm]
command = "npx"
args = ["-y", "osm-mcp"]
```

Container (multi-arch, with SBOM and build provenance):

```sh
docker run -i --rm ghcr.io/ni-c/osm-mcp
```

`-i` is required — the protocol runs over stdin and stdout. There is no port to
publish. More client recipes are in the
[client guide](https://osm-mcp.ni-c.de/guide/clients).

## Tools

| Tool                     | Description                                                                                    |
| ------------------------ | ---------------------------------------------------------------------------------------------- |
| `geocode`                | Place name/address → coordinates (Nominatim or Photon)                                         |
| `reverse_geocode`        | Coordinates → nearest address                                                                  |
| `route`                  | Distance and duration between 2+ waypoints, `foot`/`car`/`bike`; optional turn-by-turn summary |
| `route_matrix`           | Travel time/distance from every origin to every destination in one call                        |
| `optimize_route`         | Best visiting order for a set of stops (traveling-salesman, OSRM trip)                         |
| `isochrone`              | Reachable area within a time or distance budget (Valhalla, or ORS with key)                    |
| `find_nearby_pois`       | POIs around a location by category or raw OSM tag, sorted by distance (Overpass)               |
| `poi_details`            | Full OSM record of one element: opening hours, website, phone, …                               |
| `suggest_meeting_point`  | Fair meeting venue for 2–8 people (balanced travel times)                                      |
| `straight_line_distance` | Great-circle distance, computed offline                                                        |
| `map_link`               | openstreetmap.org marker / directions links, computed offline                                  |

Every place input accepts either a name/address (geocoded automatically) or
literal coordinates as `"lat,lon"`.

## Usage policies & attribution

This server talks to shared community infrastructure. It enforces the
published limits client-side, but the operator asks users to keep overall
usage light and non-commercial:

- **Data:** © [OpenStreetMap](https://www.openstreetmap.org/copyright)
  contributors, licensed under [ODbL 1.0](https://opendatacommons.org/licenses/odbl/).
- **Nominatim:** max 1 request/second, identifying User-Agent mandatory,
  results cached ([policy](https://operations.osmfoundation.org/policies/nominatim/)).
- **OSRM / Valhalla (FOSSGIS):** reasonable, non-commercial use; max 1
  request/second ([about](https://routing.openstreetmap.de/about.html)).
- **Overpass:** ~2 concurrent slo