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

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

Structured output

Every tool declares an outputSchema and answers with structuredContent
alongside the text block, so a client can use the result without parsing prose:

{
  "untrusted": true,
  "source": "openstreetmap",
  "profile": "foot",
  "engine": "osrm",
  "waypoints": ["Berlin Hauptbahnhof", "Brandenburger Tor"],
  "distance": "2.3 km",
  "distance_m": 2317,
  "duration": "29 min",
  "duration_s": 1740,
}

Every tool carries untrusted: true and source: "openstreetmap" — there
is no exception list, because OpenStreetMap is editable by anyone on earth and
no tool here answers with anything else. A client that reads only the structured
half would otherwise get a mapper's free text with no framing at all.

What this server computes — distances, durations, coordinates, which routing
engine ran — is described exactly. What comes out of OSM is described but left
open: the tag namespace has no schema, and a mapper adding payment:bitcoin
must not take poi_details out of service. The SDK validates every result
against its schema before it goes out, so a stricter shape would do exactly
that.

The control-character and BiDi stripping this server has always done to its text
now runs over the structured value too, key by key. It used to happen on the
serialized JSON, which reached every string in it for free.

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.

Not exposed, on purpose

No editing. All eleven tools are read-only against OpenStreetMap; the editing
API is not wired up at all, so there is no write mode to switch off.

No rendering and no tracking. Results are structured data plus links rather
than images — map_link hands you a URL to look at the map yourself — and there
is no state between calls.

No offline mode. Every answer comes from the public OpenStreetMap services,
under their usage policies.

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; the HTTP status is decided before a body is read.
• Every value a service answers is shaped before it reaches a result: finite
  numbers, bounded strings, one malformed element dropped rather than the
  whole listing.
• Redirects are never followed; all requests time out.

Documentation

The full guide, tool reference and security notes live at
osm-mcp.ni-c.de (source in docs/).

Development

npm install
npm run lint          # oxlint + 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.

Contributing

Issues, discussions and pull requests are welcome — see
CONTRIBUTING.md. For vulnerabilities please use
private reporting
rather than a public issue; the policy is in SECURITY.md.

License

MIT © Willi Thiel