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.

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

Choosing which tools load

OSM_ALLOW_TOOLS and OSM_DENY_TOOLS take comma-separated tool names; a trailing * matches a whole family. essential is a curated preset of six: geocode, reverse_geocode, find_nearby_pois, poi_details, route, map_link.

OSM_ALLOW_TOOLS=essential
OSM_ALLOW_TOOLS=geocode,route,find_nearby_pois
OSM_DENY_TOOLS=isochrone,optimize_route

An entry that matches no tool aborts startup and names it, so a typo cannot silently hide a tool — an absent tool is not something anyone traces back to an environment variable. A filtered tool is never registered, so it is absent from tools/list and unknown to tools/call alike.

If you run several of these servers at once, mcp-hub is the other answer — its /hub endpoint replaces every server's tools with six meta-tools.

Installation

Claude Code

claude mcp add osm -- npx -y osm-mcp

Claude Desktop

claude_desktop_config.json:

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

Codex

~/.codex/config.toml:

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

Docker

Multi-arch, with SBOM and build provenance:

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.

Through mcp-hub