geo-mcp
The geo-mcp server provides OSM-backed multimodal (walk + transit) navigation and geospatial tools for LLM applications without proprietary map APIs.
Geocoding & Reverse Geocoding: Convert place names/addresses to coordinates (
geocode) and coordinates to human-readable locations (reverse_geocode).Multimodal Route Planning: Plan walk + transit routes with adaptive strategies (A* for short trips, hierarchical transit-skeleton for longer journeys) and optional deferred processing (
plan_route).Area Loading & Caching: Load and cache OSM walk and transit graph data for a place or bounding box, enabling offline/local processing and faster queries (
load_area).Points of Interest Discovery: Find nearby OSM POIs such as cafes, pharmacies, and parks by category and radius (
find_nearby).Transit Options Lookup: List nearby transit stops and the lines serving them (
list_transit_options).Area Description: Get a structured summary of an area's major roads, neighborhoods, and landmarks for geographic context (
describe_area).Network Snapping: Snap coordinates to the nearest graph node (intersection or transit stop) for precise routing (
snap_to_network).Asynchronous Job Management: Submit, check, cancel, and list background jobs for long routing tasks (
submit_route,get_job,cancel_job,list_jobs).Offline Operation & Resilient Data Handling: Operate offline after initial OSM ingestion; uses retries, circuit breakers, and deadlines for online operations.
Provides tools for geocoding, routing, and exploring points of interest using OpenStreetMap data, enabling multimodal (walking and transit) navigation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@geo-mcp Plan a walking route from Central Park to Times Square"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
geo-mcp
OSM-backed multimodal (walk + transit) navigation MCP server. Gives LLM apps structured routing and geo tools for any distance — neighborhood walks to cross-city transit — without proprietary map APIs.
Features
Offline / local PBF: download a Geofabrik extract once (
geo-mcp ingest), then route without OverpassDistance-adaptive routing: local multimodal A* for short trips; hierarchical transit-skeleton + walk access/egress for long ones
Tiled parallel loads: walk/transit graphs from local clips or Overpass tiles
Deferred jobs + progress: long routes can return
job_id; poll withget_jobResilient OSM I/O: retries, circuit breakers, deadlines (online mode)
Transports: stdio (default) and optional Streamable HTTP
Related MCP server: Geo MCP Worker
Tools
Tool | Purpose |
| Place ↔ coordinates |
| Adaptive multimodal route (optional |
| Always-background route job |
| Job lifecycle |
| Prefetch tiles for explore/ |
| Nearby OSM POIs |
| Nearby stops and lines |
| Major roads, neighborhoods, landmarks |
| Nearest graph node (auto-loads a local tile if needed) |
Requirements
Python 3.14+
For offline clipping: osmium-tool (
brew install osmium-tool)
Install
cd /path/to/geo-mcp
uv sync
brew install osmium-tool # once, for offline bbox extractsOffline mode (recommended)
Download once, then never hit Overpass for routing:
# ~300–400 MB for Île-de-france
uv run geo-mcp ingest --region ile-de-france
uv run geo-mcp status
# Serve MCP offline
GEO_MCP_OFFLINE=true uv run geo-mcpCursor env example: set GEO_MCP_OFFLINE=true and GEO_MCP_PBF_REGION=ile-de-france. Other regions: berlin, greater-london, france. Or pass --url for any .osm.pbf.
Run
# Cursor / Claude Desktop (stdio)
uv run geo-mcp
# Optional Streamable HTTP
uv run geo-mcp --transport streamable-http --host 127.0.0.1 --port 8000
# Verbose logs
uv run geo-mcp --log-level INFOCursor config
{
"mcpServers": {
"geo-mcp": {
"command": "uv",
"args": [
"--directory",
"/path/to/geo-mcp",
"run",
"geo-mcp"
],
"env": {
"PYTHONWARNINGS": "ignore"
}
}
}
}Suggested agent flow
geocodeorigin and destinationplan_routewith coordinates (no priorload_arearequired)If the response has
job_id, pollget_jobuntilstatusiscompleted(orfailed)Optionally
describe_area/find_nearbyafter a localload_area
Tests
uv run pytestLive OSM smoke (needs network):
uv run python scripts/smoke_route.pyConfiguration
Environment variables use the GEO_MCP_ prefix. Important knobs:
Variable | Default | Meaning |
|
| Never call Overpass; require local PBF/cache |
|
| Geofabrik region for ingest |
| — | Explicit path to |
|
| Use local PBF when present |
|
| Below this → local A*; above → hierarchical |
|
| Access/egress stop search radius |
|
| Walk tile grid size (~1 km) |
|
| Parallel tile workers |
|
| Soft sync budget (long trips auto-defer) |
|
| Hard deadline per route/load |
|
| Retries per Overpass endpoint |
|
| Disk graph cache |
Architecture
src/geo_mcp/
domain/ # geo, network, pathfinding, hierarchical router
application/ # use cases, job service, DTOs
infrastructure/
resilience/ # retry, circuit breaker, deadline
graph/ # disk cache + tile store
osm/ # Nominatim, Overpass, OSMnx repository
interfaces/mcp/ # FastMCP tools (+ progress)Limits
Transit uses OSM topology and heuristic speeds (not GTFS realtime schedules)
Hierarchical routing stitches transit with walk tiles / geodesic walk fallbacks at the ends
First fetch for uncached tiles still depends on Overpass/OSMnx latency
Attribution & policy
Map data © OpenStreetMap contributors
Respect Nominatim usage policy and Overpass etiquette
Available Tools
8 toolsdescribe_areaA
Describe the loaded area's structure: axes, neighborhoods, landmarks.
Useful for giving LLMs city-design context before narrating directions.
Inputs: no named parameters. Returns: object
find_nearbyB
Find nearby points of interest (cafes, pharmacies, parks, etc.).
Inputs: lat (required), lon (required), limit, category, +1 more. Returns: result
geocodeB
Resolve a place name or address to latitude/longitude and metadata.
Inputs: query (required), limit. Returns: result
list_transit_optionsB
List nearby transit stops and the lines that serve them.
Inputs: lat (required), lon (required), limit, radius_m. Returns: result
load_areaA
Load and cache OSM walk+transit graph for a place name or bounding box.
Prefer a place query (e.g. "Le Marais, Paris") or an explicit bbox. Must be called before plan_route, describe_area, or snap_to_network.
Inputs: east, west, north, place, +2 more. Returns: object
plan_routeA
Plan a multimodal route on the loaded area graph.
modes defaults to walk+transit. Use ["walk"] for pedestrian-only. Requires a prior successful load_area call.
Inputs: origin_lat (required), origin_lon (required), destination_lat (required), destination_lon (required), +1 more. Returns: object
reverse_geocodeB
Resolve coordinates to a human-readable place.
Inputs: lat (required), lon (required). Returns: result
snap_to_networkB
Snap a coordinate to the nearest loaded graph node (intersection or stop).
Inputs: lat (required), lon (required), kind. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct action: geocoding, routing, POI discovery, transit info, area description, and graph snapping. Even similarly named tools like load_area and describe_area are clearly differentiated by their roles (loading data vs. analyzing it).
Tool names follow a consistent lowercase underscore-separated verb_noun pattern (e.g., plan_route, list_transit_options). The exceptions geocode and reverse_geocode are single-word verbs that are standard and clearly related, maintaining consistency in style.
With 8 tools, the set is well-scoped for a geo/routing server. Each tool covers a necessary function without redundancy, and the count is comfortably within the ideal 3-15 range.
The tool surface covers the core geospatial workflow: geocoding, reverse geocoding, graph loading, route planning, POI lookup, transit listing, area description, and coordinate snapping. No obvious gaps exist for the server's stated purpose; the dependency on load_area is clearly documented.
Maintenance
Related MCP Connectors
Geospatial AI MCP server — satellite imagery, embeddings, weather, GNS governance
Mobility, geocoding and nearby urban services for AI agents.
Geocoding, routing, isochrones, traffic, weather, and place search for AI agents. 19 MCP tools.
MCP server for Japan geodata: cadastral lot numbers (chiban) and reverse geocoding, for AI agents.
Related MCP Servers
- AlicenseBqualityDmaintenanceA comprehensive MCP server providing 30 tools for geocoding, routing, and OpenStreetMap data analysis. It enables AI assistants to search for locations, calculate travel routes, and perform quality assurance checks on map data.306MIT
- AlicenseNot gradedqualityCmaintenanceFree geospatial MCP server for AI agents, providing geocoding, reverse geocoding, POI search, and route planning using OpenStreetMap data via Nominatim, Overpass, and OSRM.GPL 3.0
- AlicenseAqualityDmaintenanceAn OpenStreetMap MCP server that provides location-based services including geocoding, route directions, points of interest search, and neighborhood analysis to enhance LLMs with geospatial capabilities.121MIT
- AlicenseAqualityDmaintenanceAn OpenStreetMap MCP server providing geocoding, routing, points of interest, map tiles, public transport, and energy infrastructure tools to enhance LLM location-based capabilities.16MIT