OpenStreetMap

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 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 ≥ 24
• 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

A client that cannot spawn a local process — ChatGPT connectors, Claude on the web, Cursor, LibreChat — reaches osm-mcp through mcp-hub: one container serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login behind a single password and long-lived tokens for the clients that cannot do OAuth. Its /hub endpoint puts every server behind six meta-tools, so one connector reaches all of them without N×tool schemas in the model's context, and it speaks both protocol revisions — a question this server asks travels through it to the person at the far end.

Its /config/mcp.json uses Claude Code's format, so the entry is the one you already have:

{

"mcpServers": { "osm": { "command": "npx", "args": ["-y", "osm-mcp"], "env": { "OSM_ALLOW_TOOLS": "essential" }, "denyTools": ["isochrone"] } } }

allowTools and denyTools there are the hub's own per-server filter, which is not the same thing as *_ALLOW_TOOLS in env — the difference, and the mistake it invites, are in the client guide.

Tools

| isochrone | Reachable area