osmmcp

The nervsystems-osmmcp server is a Go-based OpenStreetMap MCP server that implements the Model Context Protocol to enable large language models to interact with geospatial data. It exposes a suite of composable tools for geocoding, reverse geocoding, routing, POI search, and area analysis, designed to be chained together into workflows. Typical workflows include finding nearby places along a route, calculating routes between two points, and enriching route options with distance or emissions insights. Tools are designed with consistent parameter naming and input/output structures to facilitate composition in LLM prompts and agent plans.

To use the server, start it using the provided Go command. Once running, you can invoke individual MCP tools (e.g., geocode_address, route_fetch, find_nearby_places) through the MCP client integration or via the MCP-compliant desktop clients and dashboards. The server’s tooling supports bounding-box queries, centroid calculations, distance measurements via the Haversine formula, and polyline encoding/decoding, enabling rich geographic analysis and pipeline construction within LLM-driven workflows.

Prerequisites:

• Go 1.18+ installed on your system
• Git to clone the repository

Installation steps:

1. Clone the repository: git clone https://github.com/NERVsystems/osmmcp.git cd osmmcp

2. Build or run the server directly:

   • Build (produces a binary): go build ./... This will create a binary in the repository root (or you can build a specific module if needed).
   • Run (from source): go run ./cmd/osmmcp

3. Configure environment (optional):

   • Set OSMCP_LOG_LEVEL to control logging verbosity (debug, info, warn, error).
   • Set OSM_HOST if you want to direct the server to a specific OSM data source endpoint.

4. Verify the server is listening (default port depends on the Go implementation). You can use curl or your MCP client to connect and verify the MCP metadata and available tools.

Tips:

• If you plan to run in production, consider building a release binary and using a process manager to keep the service alive.
• Use environment variables to control logging and data source endpoints without changing code.
• When composing workflows, keep tool inputs consistent; many tools expect coordinates as latitude/longitude fields and radii in meters. The provided examples in the README show the expected parameter shapes.
• If you encounter issues with geocoding or routing, ensure your OSM data source endpoint is reachable and compatible with the server’s OSRM or Nominatim integration.
• Look out for banner notes about the composable primitives; these workflows are designed to be modular and require proper chaining for complex analyses.