{
"markdown": "# osm-mcp\n\n\n\n[](https://github.com/ni-c/osm-mcp/actions/workflows/ci.yml)\n[](https://scorecard.dev/viewer/?uri=github.com/ni-c/osm-mcp)\n![\"Socket](\"https://socket.dev/api/badge/npm/package/osm-mcp\")
\n[](https://glama.ai/mcp/servers/ni-c/osm-mcp)\n
\n[](https://www.npmjs.com/package/osm-mcp)\n[](https://github.com/ni-c/osm-mcp/pkgs/container/osm-mcp)\n[](https://mcp-hub.ni-c.de)\n
\n[](https://osm-mcp.ni-c.de)\n[](https://github.com/sponsors/ni-c)\n\n\nA [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for\n[OpenStreetMap](https://www.openstreetmap.org), built for travel planning.\n\nLets MCP clients like Claude Code, Claude Desktop or Codex answer questions about\nplaces: geocoding, walking, driving and cycling distances and durations, multi-stop\nroute optimization, isochrones and POI search — 11 tools, all read-only.\n\nEleven tools is the ceiling, not the floor: `OSM_ALLOW_TOOLS=essential`\nregisters a curated six instead, and a model picks the right tool far more\nreliably from six than from eleven — see\n[choosing which tools load](#choosing-which-tools-load).\n\nAll backends are free public OpenStreetMap services, so **no API key is required**.\nAn OpenRouteService key can be supplied optionally to switch the routing engine.\n\n\n\n \n \n ![\"An](\"https://osm-mcp.ni-c.de/architecture.svg\")
\n\n\n![\"Terminal](\"https://osm-mcp.ni-c.de/demo.gif\")
\n\n## What makes it different\n\n- **Correct walking/cycling routes.** The public OSRM demo servers ignore the\n profile segment inside the OSRM URL path and always return **car** routes\n unless the FOSSGIS `routed-foot` / `routed-bike` / `routed-car` path prefixes\n are used. Most existing OSM MCP servers get this wrong and silently return\n driving times for walking queries. This server uses the prefixes and its live\n smoke test asserts that foot routes are much slower than car routes.\n- **Policy-compliant by construction.** Per-service rate limiting (Nominatim and\n OSRM: 1 request/second), an identifying User-Agent on every request (required\n by the Nominatim usage policy), response caching, capped Overpass concurrency\n (2 slots) and automatic failover to an Overpass mirror on 429/5xx.\n- **Photon support.** Optional typo-tolerant geocoding via komoot's Photon,\n which is designed for interactive use — a better fit for LLM-driven lookups\n than hammering Nominatim.\n\n## Requirements\n\n- Node.js ≥ 22\n- Internet access to the public OpenStreetMap services (see table below)\n\n## Configuration\n\nEvery variable is optional — the server works out of the box.\n\n| Variable | Default | Description |\n| -------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `OSM_USER_AGENT` | `osm-mcp/ (+https://github.com/ni-c/osm-mcp)` | User-Agent sent to every service. Nominatim requires a real, identifying one. |\n| `NOMINATIM_BASE_URL` | `https://nominatim.openstreetmap.org` | Geocoding / reverse geocoding |\n| `PHOTON_BASE_URL` | `https://photon.komoot.io` | Typo-tolerant geocoding |\n| `OSRM_BASE_URL` | `https://routing.openstreetmap.de` | Routing, matrices, trip optimization. Must serve the `routed-{car,bike,foot}` path prefixes (the FOSSGIS layout). |\n| `OVERPASS_BASE_URL` | `https://overpass-api.de/api/interpreter,https://overpass.private.coffee/api/interpreter` | Comma-separated Overpass endpoints, tried in order on 429/5xx |\n| `VALHALLA_BASE_URL` | `https://valhalla1.openstreetmap.de` | Isochrones |\n| `ORS_API_KEY` | – | Optional [OpenRouteService](https://openrouteservice.org) key (secret). When set, routes, matrices and isochrones use ORS instead of OSRM/Valhalla. Free tier: 2000 directions/day, 40/minute. |\n| `ORS_BASE_URL` | `https://api.openrouteservice.org` | OpenRouteService endpoint |\n| `OSM_CACHE_TTL` | `3600` | Seconds identical upstream responses are served from the in-memory cache (`0` disables caching) |\n| `OSM_ALLOW_TOOLS` | no | Comma-separated tool names, `list_*` prefixes, or `essential` for a curated preset |\n| `OSM_DENY_TOOLS` | no | Same syntax; removed from whatever `OSM_ALLOW_TOOLS` left |\n\n### Choosing which tools load\n\n`OSM_ALLOW_TOOLS` and `OSM_DENY_TOOLS` take comma-separated tool names;\na trailing `*` matches a whole family. `essential` is a curated preset of\nsix: `geocode`, `reverse_geocode`, `find_nearby_pois`, `poi_details`, `route`, `map_link`.\n\n```sh\nOSM_ALLOW_TOOLS=essential\nOSM_ALLOW_TOOLS=geocode,route,find_nearby_pois\nOSM_DENY_TOOLS=isochrone,optimize_route\n```\n\nAn entry that matches no tool aborts startup and names it, so a typo cannot\nsilently hide a tool — an absent tool is not something anyone traces back to an\nenvironment variable. A filtered tool is never registered, so it is absent from\n`tools/list` and unknown to `tools/call` alike.\n\nIf you run several of these servers at once, [mcp-hub](https://mcp-hub.ni-c.de)\nis the other answer — its `/hub` endpoint replaces every server's tools with six\nmeta-tools.\n\n## Installation\n\n### Claude Code\n\n```sh\nclaude mcp add osm -- npx -y osm-mcp\n```\n\n### Claude Desktop\n\n`claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"osm\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"osm-mcp\"]\n }\n }\n}\n```\n\n### Codex\n\n`~/.codex/config.toml`:\n\n```toml\n[mcp_servers.osm]\ncommand = \"npx\"\nargs = [\"-y\", \"osm-mcp\"]\n```\n\n### Docker\n\nMulti-arch, with SBOM and build provenance:\n\n```sh\ndocker run -i --rm ghcr.io/ni-c/osm-mcp\n```\n\n`-i` is required — the protocol runs over stdin and stdout. There is no port to\npublish. More client recipes are in the\n[client guide](https://osm-mcp.ni-c.de/guide/clients).\n\n### Through mcp-hub\n\nA client that cannot spawn a local process — ChatGPT connectors, Claude on the web,\nCursor, LibreChat — reaches osm-mcp through [mcp-hub](https://mcp-hub.ni-c.de): one\ncontainer serves many stdio MCP servers over Streamable HTTP, with an OAuth 2.1 login\nbehind a single password and long-lived tokens for the clients that cannot do OAuth. Its\n`/hub` endpoint puts every server behind six meta-tools, so one connector reaches all of\nthem without N×tool schemas in the model's context, and it speaks both protocol revisions\n— a question this server asks travels through it to the person at the far end.\n\nIts `/config/mcp.json` uses Claude Code's format, so the entry is the one you already\nhave:\n\n```json\n{\n \"mcpServers\": {\n \"osm\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"osm-mcp\"],\n \"env\": { \"OSM_ALLOW_TOOLS\": \"essential\" },\n \"denyTools\": [\"isochrone\"]\n }\n }\n}\n```\n\n`allowTools` and `denyTools` there are the hub's **own** per-server filter, which is not\nthe same thing as `*_ALLOW_TOOLS` in `env` — the difference, and the mistake it invites,\nare in the [client guide](https://osm-mcp.ni-c.de/guide/clients#through-mcp-hub).\n\n## Tools\n\n| Tool | Description |\n| ------------------------ | ---------------------------------------------------------------------------------------------- |\n| `geocode` | Place name/address → coordinates (Nominatim or Photon) |\n| `reverse_geocode` | Coordinates → nearest address |\n| `route` | Distance and duration between 2+ waypoints, `foot`/`car`/`bike`; optional turn-by-turn summary |\n| `route_matrix` | Travel time/distance from every origin to every destination in one call |\n| `optimize_route` | Best visiting order for a set of stops (traveling-salesman, OSRM trip) |\n| `isochrone` | Reachable area within a time or distance budget (Valhalla, or ORS with key) |\n| `find_nearby_pois` | POIs around a location by category or raw OSM tag, sorted by distance (Overpass) |\n| `poi_details` | Full OSM record of one element: opening hours, website, phone, … |\n| `suggest_meeting_point` | Fair meeting venue for 2–8 people (balanced travel times) |\n| `straight_line_distance` | Great-circle distance, computed offline |\n| `map_link` | openstreetmap.org marker / directions links, computed offline |\n\nEvery place input accepts either a name/address (geocoded automatically) or\nliteral coordinates as `\"lat,lon\"`.\n\n### Structured output\n\nEvery tool declares an `outputSchema` and answers with `structuredContent`\nalongside the text block, so a client can use the result without parsing prose:\n\n```jsonc\n{\n \"untrusted\": true,\n \"source\": \"openstreetmap\",\n \"profile\": \"foot\",\n \"engine\": \"osrm\",\n \"waypoints\": [\"Berlin Hauptbahnhof\", \"Brandenburger Tor\"],\n \"distance\": \"2.3 km\",\n \"distance_m\": 2317,\n \"duration\": \"29 min\",\n \"duration_s\": 1740,\n}\n```\n\n**Every** tool carries `untrusted: true` and `source: \"openstreetmap\"` — there\nis no exception list, because OpenStreetMap is editable by anyone on earth and\nno tool here answers with anything else. A client that reads only the structured\nhalf would otherwise get a mapper's free text with no framing at all.\n\nWhat this server computes — distances, durations, coordinates, which routing\nengine ran — is described exactly. What comes out of OSM is described but left\nopen: the tag namespace has no schema, and a mapper adding `payment:bitcoin`\nmust not take `poi_details` out of service. The SDK validates every result\nagainst its schema before it goes out, so a stricter shape would do exactly\nthat.\n\nThe control-character and BiDi stripping this server has always done to its text\nnow runs over the structured value too, key by key. It used to happen on the\nserialized JSON, which reached every string in it for free.\n\n## Usage policies & attribution\n\nThis server talks to shared community infrastructure. It enforces the\npublished limits client-side, but the operator asks users to keep overall\nusage light and non-commercial:\n\n- **Data:** © [OpenStreetMap](https://www.openstreetmap.org/copyright)\n contributors, licensed under [ODbL 1.0](https://opendatacommons.org/licenses/odbl/).\n- **Nominatim:** max 1 request/second, identifying User-Agent mandatory,\n results cached ([policy](https://operations.osmfoundation.org/policies/nominatim/)).\n- **OSRM / Valhalla (FOSSGIS):** reasonable, non-commercial use; max 1\n request/second ([about](https://routing.openstreetmap.de/about.html)).\n- **Overpass:** ~2 concurrent slots per IP, <10 000 queries/day\n ([wiki](https://wiki.openstreetmap.org/wiki/Overpass_API)).\n- **Photon:** fair use ([photon.komoot.io](https://photon.komoot.io)).\n\nFor heavy or commercial use, self-host the services and point the\n`*_BASE_URL` variables at your instances.\n\n## Not exposed, on purpose\n\n**No editing.** All eleven tools are read-only against OpenStreetMap; the editing\nAPI is not wired up at all, so there is no write mode to switch off.\n\n**No rendering and no tracking.** Results are structured data plus links rather\nthan images — `map_link` hands you a URL to look at the map yourself — and there\nis no state between calls.\n\n**No offline mode.** Every answer comes from the public OpenStreetMap services,\nunder their usage policies.\n\n## Safety\n\n- All tools are **read-only**; the server never writes to OpenStreetMap.\n- No credentials are required; the optional `ORS_API_KEY` is removed from the\n process environment after loading and redacted from error messages.\n- OSM-sourced content (names, addresses, tags) is marked as untrusted data in\n tool results so the model treats it as data, not instructions.\n- Upstream error bodies are truncated and HTML error pages dropped before they\n reach the model context; the HTTP status is decided before a body is read.\n- Every value a service answers is shaped before it reaches a result: finite\n numbers, bounded strings, one malformed element dropped rather than the\n whole listing.\n- Redirects are never followed; all requests time out.\n\n## Documentation\n\nThe full guide, tool reference and security notes live at\n**[osm-mcp.ni-c.de](https://osm-mcp.ni-c.de)** (source in [`docs/`](docs/)).\n\n## Development\n\n```sh\nnpm install\nnpm run lint # oxlint + prettier\nnpm test # unit tests (all upstream APIs mocked)\nnpm run test:coverage\nnpm run build\nnpm run smoke # opt-in LIVE test against the real public services\n```\n\n## Releasing\n\nTag-driven, no manual publish step:\n\n1. Move the `[Unreleased]` entries into a new `## [x.y.z] - YYYY-MM-DD` section in\n `CHANGELOG.md` and bump `package.json`.\n2. `npm run lint && npm run build && npm run test:coverage`.\n3. Commit, then a **signed annotated** tag: `git tag -s vx.y.z -m \"vx.y.z\"`.\n4. `git push origin main vx.y.z`.\n\n`release.yml` then runs the tests, publishes to npm with provenance via Trusted\nPublishing (no token secret involved), creates the GitHub release from the\nCHANGELOG section, and publishes to the\n[MCP registry](https://registry.modelcontextprotocol.io) as\n`io.github.ni-c/osm-mcp`. `ci.yml` pushes the multi-arch image to GHCR on the\nsame tag.\n\nIf the registry step fails, fix it on `main` and dispatch the\n`Publish to MCP Registry` workflow — do **not** re-run the tag job, which would\ncheck out the old tree.\n\n## Contributing\n\nIssues, discussions and pull requests are welcome — see\n[CONTRIBUTING.md](CONTRIBUTING.md). For vulnerabilities please use\n[private reporting](https://github.com/ni-c/osm-mcp/security/advisories/new)\nrather than a public issue; the policy is in [SECURITY.md](SECURITY.md).\n\n## License\n\n[MIT](LICENSE) © Willi Thiel\n",
"bytes": 18009,
"sha": "b57a7053fdb790add7cc0c0dfacb800fc38c5f1e7aeebf23dc82ce90face39ca",
"repo_slug": "ni-c/osm-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_ni_c_osm_mcp_bae30c10/readme"
}