osm

This MCP server provides access to OpenStreetMap-based geocoding and distance APIs. It implements geocoding and reverse geocoding via Nominatim, distance calculations using OSRM, and a local haversine distance implementation. The server is intended for experimentation and understanding MCP server workflows; for production use you should point the server at your own Nominatim and OSRM instances. The index.js file in the project contains the base URLs (Nominatim and OSRM) and can be adjusted to switch between public and custom servers. You can query the server to convert coordinates into addresses, look up coordinates for a given place, and compute both straight-line and route distances between two points.

The available capabilities include:

• Geocoding: find coordinates or location details for a given place via Nominatim.
• Reverse geocoding: obtain a human-readable address or place details from a pair of coordinates via Nominatim.
• Route distance: calculate distance between two points using OSRM routing data.
• Haversine distance: compute the great-circle distance between two coordinates using a simple haversine implementation.

To use these tools, send prompts or requests through the MCP protocol to the server. If you provide two locations, you can get both their coordinates and the route distance between them. You can also request the distance directly between two known cities, and the server will fetch coordinates and compute the straight-line distance as well as the route distance if you request it.

Prerequisites:

• Node.js 20 or newer installed on your machine
• Git (optional, for cloning)

Install steps:

1. Clone or download the MCP server project

   • git clone https://github.com/your-org/osm-mcp-server.git
   • cd osm-mcp-server

2. Install dependencies

   • npm install

3. Install the MCP SDK (if not already present)

   • npm install @modelcontextprotocol/sdk

4. Configure the MCP server in a local workspace (example provided in the README):

   • Create a .vscode directory at your workspace root
   • Create a file .vscode/mcp.json with your server configuration, for example:

{
  "servers": {
    "tpp6me-osm-mcp-server": {
      "type": "stdio",
      "command": "/path/to/node",
      "args": [
        "/path/to/index.js"
      ],
      "env": {
      }
    }
  }
}

5. Start the server (adjust the paths to your environment):

• node /path/to/index.js

6. Optional: configure environment variables in the mcp.json if you want to point to custom Nominatim or OSRM servers, e.g. NOMINATIM_BASE_URL and OSRM_BASE_URL as described in the README.

Notes:

• Ensure you have network access to the Nominatim and OSRM endpoints you plan to use.
• For production, point NOMINATIM_BASE_URL and OSRM_BASE_URL to your own servers and monitor usage.

Tips and considerations:

• The server relies on external Nominatim and OSRM endpoints. If you see rate limits, switch to a dedicated instance or adjust query frequency.
• You can customize NOMINATIM_BASE_URL and OSRM_BASE_URL in index.js to point to your own servers for stable production usage.
• The README mentions a haversine distance function; this is useful for quick straight-line distance estimates when routing data is not required.
• When running in an editor like VS Code, you can store the mcp.json configuration under .vscode (local) or ~/.vscode (global) as described in the README to share configurations across projects.
• Ensure your Node.js version matches the project requirement (Node 20+).