osm-mcp
Provides geospatial data services using OpenStreetMap, including geocoding, reverse geocoding, point-of-interest search, isochrone generation, and bounding box density summaries.
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., "@osm-mcp Which cafés are within a 15-minute walk from Bukit Bintang MRT?"
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.
Open MCP Data Server
An MCP server that gives Claude (or Cursor, or Claude Code) live geospatial data — geocoding, POI search, isochrones, and area density — over open data.
One-line pitch: turn real open data sources into tools any LLM client can call directly. The model orchestrates the calls; this server does the fetching, caching, rate-limiting, and typed validation.
The hook (demo)
Ask Claude Desktop a real geography question and it calls your tools directly:
You (in Claude Desktop):
"I'm opening a coffee shop. Find all existing cafés within a 15-minute walk
of Bukit Bintang MRT, and tell me the postcode centroid so I can cross-check
rent data."
Claude:
→ isochrone(lat=3.1498, lon=101.7149, mode="walk", minutes=15)
→ pois(lat=3.1499, lon=101.7144, radius_m=1200, categories=["cafe"])
→ reverse_geocode(lat=3.1499, lon=101.7144)
← cafe list (12 matches), postcode "55100", centroid coords
Claude:
"There are 12 cafés within a 15-min walk. The postcode centroid is 55100
(Bukit Bintang). Here's the list, sorted by distance…"The user never sees an API key or an HTTP call — the model orchestrates the tools. That orchestration, made possible by the server's tool design, is the point of this project.
📸 GIF of a live Claude Desktop session goes here on first publish.
Related MCP server: geocontext
How it works
┌─────────────────────┐ MCP (JSON-RPC over stdio)
│ LLM Client │ ─────────────────────────────────────┐
│ (Claude Desktop / │ │
│ Cursor / Code) │ ◄──── tool schemas advertised │
└─────────────────────┘ ▼
┌─────────────────────────────┐
│ Open MCP Data Server │
│ (FastMCP Python process) │
│ │
│ @mcp.tool: geocode │
│ @mcp.tool: reverse_geocode │
│ @mcp.tool: pois │
│ @mcp.tool: isochrone │
│ @mcp.tool: bbox_summary │
│ │
│ TTLCache + rate limiting │
└──────────────┬──────────────┘
│ https GET/POST
┌──────────────────────────┼──────────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌────────────────────┐ ┌─────────────────┐
│ OSM Nominatim │ │ Overpass API │ │ OSRM │
│ (geocoding) │ │ (POIs by amenity) │ │ (isochrones) │
└─────────────────┘ └────────────────────┘ └─────────────────┘Each tool is a thin async function that fetches upstream data through a shared cache + per-host rate limiter, validates it with Pydantic, and returns a typed result. Inputs are enum-constrained — callers never supply raw Overpass QL.
Tools
Tool | Description | Units |
| Forward geocode a place name → coordinate. | lat/lon decimal degrees |
| Coordinate → human-readable address. | decimal degrees → string |
| Points of interest within a radius, by category. | metres; counts |
| Reachable-area polygon within a time budget. | minutes; polygon |
| Counts of key amenities inside a bounding box (density helper). | counts |
mode ∈ {walk, drive, transit}. categories are enum-constrained
(cafe, restaurant, retail, transit, school, attraction,
accommodation, bank, healthcare) — all Overpass queries are built
server-side.
Quick start
git clone https://github.com/abangbroy/osm-mcp.git
cd osm-mcp
python -m venv .venv && .venv\Scripts\activate # Windows
# source .venv/bin/activate # macOS/Linux
pip install -e ".[dev]"Run standalone over stdio:
osm-mcp # or: python -m osm_mcpOr install the published package directly:
uvx osm-mcp # or: pip install osm-mcpSet
USER_AGENT(see.env.example) to a descriptive value — Nominatim usage policy requires it.
Claude Desktop config
Add to claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"osm-mcp": {
"command": "C:\\path\\to\\osm-mcp\\.venv\\Scripts\\osm-mcp.exe",
"args": []
}
}
}With the published package:
{
"mcpServers": {
"osm-mcp": {
"command": "uvx",
"args": ["osm-mcp"]
}
}
}Cursor config
Point Cursor at the same command via Settings → MCP → Add Server, using
osm-mcp (local venv) or uvx osm-mcp (published).
Tests
pytest --cov=osm_mcp --cov-report=term-missingUpstream dependencies & rate-limit policy
All upstream APIs are free-tier and shared/public, so they are rate-limited. This server respects their usage terms:
TTL cache (
CACHE_TTL_SECONDS, default 24h) + per-host rate limiting (RATE_LIMIT_MIN_INTERVAL_SECONDS, default 1s — Nominatim's policy ceiling).A compliant
User-Agentheader (configurable; required by Nominatim).Bounded retry with exponential backoff for transient errors (429/502/503/ 504, timeouts), honoring
Retry-After.transitmode falls back to the OSRMfootprofile — OSRM has no transit router. For real transit isochrones, self-host a transit router and pointOSRM_BASE_URLat it. This is a documented limitation, stated openly.For production throughput, self-host Nominatim / Overpass / OSRM and set the
*_BASE_URLenv vars.
Attribution: data © OpenStreetMap contributors (ODbL). Code is MIT; data attribution must accompany any reuse.
Configuration
All settings are environment-driven (see .env.example):
Variable | Default | Purpose |
|
| Geocoding upstream |
|
| POI upstream |
|
| Routing upstream |
|
| Required by Nominatim policy |
|
| TTL cache sizing |
|
| Per-host request spacing |
|
| Upstream call timeout |
Publishing
v1 ships stdio transport. Releases are automated:
PyPI — pushing a
v*tag runspublish.yml, which re-runs the tests and lint, verifies the tag matches the version inpyproject.toml, builds, and uploads via Trusted Publishing (OIDC — no API token is stored in the repo).git tag v0.1.0 && git push origin v0.1.0Requires a one-time pending publisher on PyPI — see the header comment in
publish.ymlfor the exact field values.Official MCP registry — submit
server.jsonat registry.modelcontextprotocol.io once the PyPI release is live. The server is registered asio.github.abangbroy/osm-mcp; theio.github.<user>/namespace is what proves GitHub ownership.
SSE-only transports are deprecated since MCP spec 2025-03-26. A Streamable HTTP transport is the planned v2 stretch (no SSE).
Learned in public
This project is a portfolio piece. A few things I learned openly while building it, rather than claiming prior mastery:
FastMCP packaging — wiring
@mcp.tooldecorators to Pydantic-typed signatures and exposing the bounds in the generated JSON schema (so the model sees the limits, not just gets rejected by them).OSRM as an isochrone source — OSRM has no native isochrone endpoint; the radial-sampling +
/tableapproach is a public-methodology workaround.Overpass
(poly:)coordinate order — it expects latitude-then-longitude, the opposite of GeoJSON; getting this wrong returns HTTP 400 live.
License
MIT — see LICENSE.
Available Tools
6 toolsbbox_summaryA
Counts of key amenities inside a bounding box (a light density helper).
Units: all coordinates decimal degrees. min is south-west,
max is north-east, so min_lat <= max_lat and
min_lon <= max_lon are required. categories defaults to a
sensible set when omitted.
Example: bbox_summary(min_lat=3.14, min_lon=101.70,
max_lat=3.16, max_lon=101.72)
Inputs: max_lat (required), max_lon (required), min_lat (required), min_lon (required), +1 more. Returns: Counts of key amenities inside a bounding box (light density helper). Coordinat…
geocodeA
Forward geocode a place name to a WGS84 coordinate (decimal degrees).
Units: latitude/longitude in decimal degrees. Example: geocode(query="KL Sentral") -> GeoPoint(lat=3.1355, lon=101.7044)
Inputs: query (required). Returns: A WGS84 coordinate.
isochroneA
Reachable-area polygon within a travel-time budget.
Units: lat/lon in decimal degrees; minutes in minutes (1-120);
polygon ring as [lon, lat] pairs; area_m2 in square metres.
Example: isochrone(lat=3.15, lon=101.71, mode="walk", minutes=10)
Inputs: lat (required), lon (required), mode (required), minutes (required). Returns: Reachable area polygon within a time budget. ``polygon`` is a list of ``[lon, l…
pingA
Health-check tool.
Returns {"status": "ok"} so any MCP client can confirm reachability.
Example: ping() -> {"status": "ok"}
Inputs: no named parameters. Returns: object
poisA
Points of interest within radius_m of a point, grouped by category.
Units: lat/lon decimal degrees; radius_m metres (max 5000).
categories is enum-constrained (no free-text queries).
Example: pois(lat=3.15, lon=101.71, radius_m=500,
categories=["cafe","transit"])
Inputs: lat (required), lon (required), radius_m (required), categories (required). Returns: POIs within ``radius_m`` of a point.
reverse_geocodeA
Reverse geocode a coordinate to a human-readable address.
Units: lat/lon in decimal degrees; returns a display-name string. Example: reverse_geocode(lat=3.15, lon=101.71) -> "Bukit Bintang, ..."
Inputs: lat (required), lon (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct spatial operation: forward and reverse geocoding are clearly opposed, while isochrone, pois, and bbox_summary are differentiated by query shape (travel budget, radius, bounding box) and return type. There is no real overlap that would cause an agent to select the wrong tool confidently.
All names are lowercase snake_case, which helps, but the convention is mixed: geocode/reverse_geocode/ping are verb-like, while isochrone, pois, and bbox_summary are noun-like descriptors. The pattern is readable but not consistently verb_noun.
Six tools is a well-scoped size for an OSM-focused server. Each tool covers a distinct geospatial need without redundancy, and the set does not feel either thin or bloated.
The server covers core geospatial workflows: geocoding, reverse geocoding, reachability, POI lookup, and area density summaries. It lacks advanced routing or direct OSM element retrieval, but these are not core to the apparent purpose and can be worked around.
Maintenance
Related MCP Connectors
MCP server for Japan geodata: cadastral lot numbers (chiban) and reverse geocoding, for AI agents.
Geospatial AI MCP server — satellite imagery, embeddings, weather, GNS governance
MCP server giving Claude AI access to 22+ NYC public-record databases for real estate due diligence
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that gives LLMs access to geographic data conversion tools, enabling transformations between different formats like WKT, GeoJSON, CSV, TopoJSON, and KML, as well as performing reverse geocoding.912 npm18MIT
- AlicenseNot gradedqualityFmaintenanceAn experimental MCP server providing spatial context for LLMs by interfacing with French Geoplateforme services. It enables tasks such as geocoding, altitude lookups, and querying administrative, cadastral, or urban planning data.5 npm4MIT
- AlicenseAqualityDmaintenanceAn MCP server that provides AI agents with geospatial analytics by querying Overture Maps data directly from S3, enabling place analytics, building composition, land use classification, and transportation analysis.135MIT
- FlicenseNot gradedqualityBmaintenanceMCP server that enables LLMs to create and control interactive MapLibre maps by placing markers, drawing paths, and rendering polygons directly in Claude Desktop.1-