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.

---

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
geocode(query)	Forward geocode a place name → coordinate.	lat/lon decimal degrees
reverse_geocode(lat, lon)	Coordinate → human-readable address.	decimal degrees → string
pois(lat, lon, radius_m, categories)	Points of interest within a radius, by category.	metres; counts
isochrone(lat, lon, mode, minutes)	Reachable-area polygon within a time budget.	minutes; polygon [lon,lat]; area m²
bbox_summary(min_lat, min_lon, max_lat, max_lon, categories?)	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_mcp

Or install the published package directly:

uvx osm-mcp        # or: pip install osm-mcp

Set 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-missing

---

Upstream 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-Agent header (configurable; required by Nominatim).
• Bounded retry with exponential backoff for transient errors (429/502/503/ 504, timeouts), honoring Retry-After.
• transit mode falls back to the OSRM foot profile — OSRM has no transit router. For real transit isochrones, self-host a transit router and point OSRM_BASE_URL at it. This is a documented limitation, stated openly.
• For production throughput, self-host Nominatim / Overpass / OSRM and set the *_BASE_URL env 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
NOMINATIM_BASE_URL	https://nominatim.openstreetmap.org	Geocoding upstream
OVERPASS_BASE_URL	https://overpass-api.de	POI upstream
OSRM_BASE_URL	https://router.project-osrm.org	Routing upstream
USER_AGENT	osm-mcp/0.1.0 (...)	Required by Nominatim policy
CACHE_MAXSIZE / CACHE_TTL_SECONDS	2048 / 86400	TTL cache sizing
RATE_LIMIT_MIN_INTERVAL_SECONDS	1.0	Per-host request spacing
HTTP_TIMEOUT_SECONDS	15.0	Upstream call timeout

---

Publishing

v1 ships stdio transport. Releases are automated:

1. PyPI — pushing a v* tag runs publish.yml, which re-runs the tests and lint, verifies the tag matches the version in pyproject.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.0
   

   Requires a one-time pending publisher on PyPI — see the header comment in publish.yml for the exact field values.

2. Official MCP registry — submit server.json at registry.modelcontextprotocol.io once the PyPI release is live. The server is registered as io.github.abangbroy/osm-mcp; the io.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.tool decorators 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 + /table approach 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.