osm-mcp-server

osm-mcp-server

An MCP server that lets AI assistants use OpenStreetMap: find places, look up addresses, query map features with Overpass, search around a point, plan routes, visiting orders, travel time tables and reachable areas with Valhalla, and look up which tags mappers use with taginfo.

Tools

Tool	Service	What it does
osm_geocoding	Nominatim	Finds places by name or address. Returns several candidates (default 5, up to 20), because names are often ambiguous. Can be limited to countries and asked for a language.
osm_reverse_geocoding	Nominatim	Finds the place and the address at a coordinate.
osm_overpass_query	Overpass API	Runs an Overpass QL query and returns the matching elements (default 100, up to 1000), the total count, and when the data was last updated.
osm_search_nearby	Overpass API	Finds features with given tags around a point, nearest first, without writing Overpass QL (e.g. amenity=restaurant and cuisine=ramen within 500 m). Can also filter by name or brand in any language.
osm_routing	Valhalla	Plans a route through 2 to 20 locations by car, on foot, by bicycle and more. Returns the distance, the travel time, turn-by-turn directions, where each location was placed on the road network, and the route line on request.
osm_optimized_route	Valhalla	Finds the quickest order to visit 3 to 20 locations, keeping the first and the last, and returns that route with the visiting order and where each location was placed.
osm_route_matrix	Valhalla	Travel time and distance from every source to every target (up to 25 each), with where each location was placed on the road network and the name of the road it is on.
osm_isochrone	Valhalla	Returns the area reachable from a point within up to four travel times or distances as GeoJSON polygons, and where the start was placed on the road network.
osm_taginfo_keys	taginfo	Finds tag keys whose name contains a word, most used first.
osm_taginfo_search	taginfo	Finds tags of any key whose value contains a word, most used first, for when the key is not known (convenience finds shop=convenience).
osm_taginfo_values	taginfo	Lists the values used with a key, most used first, optionally only those containing a word (e.g. cuisine values with ramen).
osm_taginfo_tag	taginfo	Describes a tag or a key: how often it is used on nodes, ways and relations, its OSM wiki description in English and one more language, and the tags most often used with it.

The Valhalla tools move each location onto the nearest road, path or ferry line that the chosen way of travel can use, and say where that is, how far it moved, and the name of what it landed on. Check this when a result looks wrong: a point in Tokyo Bay lands on a ferry line 3.3 km away, and walking there comes out at over 2000 km because it goes by ferry to Kyushu and back.

All tools are read-only. Each returns structured content with an output schema, and the same JSON as text for clients that do not read structured content. Errors from the services, such as an Overpass parse error or a place Valhalla cannot reach, come back as tool errors with the service's own message, so the assistant can correct the request.

Setup

Requires Node.js 22.12 or later.

git clone https://github.com/yuiseki/osm-mcp-server.git
cd osm-mcp-server
npm install   # also builds build/index.js

Then register build/index.js with your MCP client. For Claude Code:

claude mcp add osm -- node /path/to/osm-mcp-server/build/index.js

For Claude Desktop and other clients that use a JSON config:

{
  "mcpServers": {
    "osm": {
      "command": "node",
      "args": ["/path/to/osm-mcp-server/build/index.js"]
    }
  }
}

Or run it with Docker:

docker build -t osm-mcp-server .
docker run -i --rm osm-mcp-server

Choosing the servers

By default the tools use the public OpenStreetMap services. To use your own, set these environment variables:

Variable	Default
NOMINATIM_URL	https://nominatim.openstreetmap.org
OVERPASS_URL	https://overpass-api.de/api
VALHALLA_URL	https://valhalla1.openstreetmap.de
TAGINFO_URL	https://taginfo.openstreetmap.org

For example:

{
  "mcpServers": {
    "osm": {
      "command": "node",
      "args": ["/path/to/osm-mcp-server/build/index.js"],
      "env": {
        "NOMINATIM_URL": "https://nominatim.example.org",
        "OVERPASS_URL": "https://overpass.example.org/api",
        "VALHALLA_URL": "https://valhalla.example.org",
        "TAGINFO_URL": "https://taginfo.example.org"
      }
    }
  }
}

The public services are shared, run by volunteers, and each has a usage policy that limits how often you may call it (for example Nominatim's). For heavy use, run your own. Every request carries a User-Agent that names this project.

Development

npm run lint        # type-check the source and the tests
npm test            # unit tests, and the built server over stdio against a local stub of the services
npm run test:live   # the built server against real services

npm test needs no network and runs in CI on Node 22 and 24. npm run test:live is not part of CI. By default it uses the maintainer's self-hosted services; set the variables above to test against your own.

License

MIT. Map data © OpenStreetMap contributors, available under the Open Database License.