ni-c/osm-mcp

A Model Context Protocol (MCP) server for
OpenStreetMap, built for travel planning.
Lets MCP clients like Claude Code, Claude Desktop or Codex answer questions about
places: geocoding, walking, driving and cycling distances and durations, multi-stop
route optimization, isochrones and POI search — 11 tools, all read-only.
Eleven tools is the ceiling, not the floor: OSM_ALLOW_TOOLS=essential
registers a curated six instead, and a model picks the right tool far more
reliably from six than from eleven — see
choosing which tools load.
All backends are free public OpenStreetMap services, so **no API key is required**.
An OpenRouteService key can be supplied optionally to switch the routing engine.
is resolved against the colour scheme of the page showing it, so GitHub
picks the variant that matches its own theme toggle. npm strips and
when it sanitises the README and keeps the , which is why that
fallback brings its own dark card instead of relying on a media query. -->
What makes it different
- **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 the next Overpass endpoint on anything
but a malformed query, within one 50-second budget per call.
- **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/ (+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://z.overpass-api.de/api/interpreter,https://lz4.overpass-api.de/api/interpreter | Comma-separated Overpass endpoints, tried in order until one answers (a malformed query stops the walk) |
| VALHALLA_BASE_URL | https://valhalla1.openstreetmap.de | Isochrones |
| ORS_API_KEY | – | Optional OpenRouteService 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) |
| OSM_ALLOW_TOOLS | no | Comma-separated tool names, list_* prefixes, or essential for a curated preset |