osm-mcp

An MCP server for OpenStreetMap: 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

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.

Related MCP server: Geo MCP Worker

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.

Install

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

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

Tools

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 contributors, licensed under ODbL 1.0.

• Nominatim: max 1 request/second, identifying User-Agent mandatory, results cached (policy).

• OSRM / Valhalla (FOSSGIS): reasonable, non-commercial use; max 1 request/second (about).

• Overpass: ~2 concurrent slots per IP, <10 000 queries/day (wiki).

• Photon: fair use (photon.komoot.io).

For heavy or commercial use, self-host the services and point the *_BASE_URL variables at your instances.

Safety

• All tools are read-only; the server never writes to OpenStreetMap.

• No credentials are required; the optional ORS_API_KEY is removed from the process environment after loading and redacted from error messages.

• OSM-sourced content (names, addresses, tags) is marked as untrusted data in tool results so the model treats it as data, not instructions.

• Upstream error bodies are truncated and HTML error pages dropped before they reach the model context.

• Redirects are never followed; all requests time out.

Development

npm install
npm run lint          # eslint + prettier
npm test              # unit tests (all upstream APIs mocked)
npm run test:coverage
npm run build
npm run smoke         # opt-in LIVE test against the real public services

Releasing

Tag-driven, no manual publish step:

1. Move the [Unreleased] entries into a new ## [x.y.z] - YYYY-MM-DD section in CHANGELOG.md and bump package.json.

2. npm run lint && npm run build && npm run test:coverage.

3. Commit, then a signed annotated tag: git tag -s vx.y.z -m "vx.y.z".

4. git push origin main vx.y.z.

release.yml then runs the tests, publishes to npm with provenance via Trusted Publishing (no token secret involved), creates the GitHub release from the CHANGELOG section, and publishes to the MCP registry as io.github.ni-c/osm-mcp. ci.yml pushes the multi-arch image to GHCR on the same tag.

If the registry step fails, fix it on main and dispatch the Publish to MCP Registry workflow — do not re-run the tag job, which would check out the old tree.

License

MIT