Maps MCP Server

An MCP server providing geocoding, routing, isochrones and POI-by-proximity search. Answers natural-language questions like:

"Give me all Best Western hotels within 50 km of Nuremberg." "Give me all Best Western hotels an hour's drive from Nuremberg."

It runs on top of two self-hosted, free, OpenStreetMap-based backends:

• Valhalla — routing engine for driving routes, isochrones (areas reachable within X minutes), and time/distance matrices.

• Nominatim — geocoder turning place names / addresses into coordinates.

The POIs it searches over default to the Best Western DACH hotel set, loaded from OpenStreetMap via Overpass (coordinates come ready-made from OSM — no geocoding step). A curated CSV/JSON file can also be imported to supplement OSM coverage. Any ad-hoc list of places can be passed to a query.

Why these backends (and not Google Maps)

Google Maps' "official" MCP server is experimental, and isochrones aren't a first-class capability there. For the "an hour's drive" question, a real routing engine is required — a circle on a map is wrong.

Related MCP server: chuk-mcp-geocoder

Architecture

flowchart TB
    %% ============ Client ============
    Agent["🤖 JQuad Agent<br/><b>Client</b><br/><i>Consumes the maps MCP server<br/>via skills/maps/SKILL.md<br/>Forwards user Bearer token</i>"]

    %% ============ The maps server ============
    subgraph MapsServer["maps-mcp-server  (FastMCP, Python, :8000)"]
        direction TB

        Tools["🔧 MCP Tools  (9 exposed)<br/><i>geocode · reverse_geocode · isochrone<br/>route · distance_matrix · find_within<br/>ingest_poi · list_poi · maps_health</i>"]

        Orchestrator["🧭 Query Orchestrator<br/><b>src/services/query_orchestrator.py</b><br/><i>find_within spatial filtering:<br/>• distance budget → matrix filter<br/>• time budget → isochrone + point-in-polygon<br/>• chunked Valhalla matrix calls</i>"]

        GeoHelpers["📐 Geo Helpers  (pure)<br/><b>src/tools/geo.py</b><br/><i>haversine_km · point_in_polygon<br/>parse_within (budget string parser)</i>"]

        POIStore["💾 POI Store<br/><b>src/services/poi_store.py</b><br/><i>JSON cache of geocoded POIs<br/>upsert/dedup by place_id</i>"]

        subgraph Sources["POI Sources  (ingest only)"]
            direction LR
            OverpassC["Overpass Client<br/><i>brand + area → OSM POIs<br/>(coordinates ready-made)</i>"]
            CSVImporter["CSV/JSON Importer<br/><i>curated / supplemental data</i>"]
        end

        Tools --> Orchestrator
        Tools --> POIStore
        Tools --> Sources
        Orchestrator --> GeoHelpers
        Orchestrator --> POIStore
        Sources --> POIStore
    end

    %% ============ Backends ============
    subgraph Backends["Backend services  (sibling pods)"]
        direction LR
        Nominatim["🌍 Nominatim  :8080<br/><b>Geocoder</b><br/><i>place name / address → lat, lon<br/>(mediagis/nominatim, Germany extract)</i>"]
        Valhalla["🛣️ Valhalla  :8002<br/><b>Routing engine</b><br/><i>isochrones · routes · time-distance matrix<br/>(gisops/valhalla, Germany extract)</i>"]
    end

    %% ============ External ============
    OverpassAPI["📡 Overpass API<br/><b>POI ingest source (read-only)</b><br/><i>overpass-api.de (public)<br/>or self-hosted instance</i>"]

    %% ============ Data stores ============
    POIPVC[("📁 POI Data PVC<br/>/app/data/poi<br/><i>bestwestern-de.json cache</i>")]
    OSMData[("🗺️ OSM Extract<br/>Germany PBF<br/><i>shared by Valhalla + Nominatim</i>")]

    %% ============ Connections ============
    Agent -- "MCP/HTTP :8000<br/>(Bearer token)" --> Tools

    Tools -- "geocode / reverse_geocode<br/>resolve place names" --> Nominatim
    Orchestrator -- "isochrone polygon<br/>distance matrix · route" --> Valhalla

    OverpassC -- "POST Overpass QL<br/>(one-shot cache-fill)" --> OverpassAPI
    CSVImporter -- "reads" --> POISourceFiles["📄 CSV/JSON files<br/>(curated, optional)"]

    POIStore -- "read/write cache" --> POIPVC
    Nominatim --- OSMData
    Valhalla --- OSMData

    %% ============ Styling ============
    classDef client fill:#e1f5ff,stroke:#0288d1,stroke-width:2px,color:#01579b
    classDef server fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,color:#e65100
    classDef backend fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,color:#1b5e20
    classDef external fill:#fce4ec,stroke:#c62828,stroke-width:2px,color:#b71c1c
    classDef store fill:#f3e5f5,stroke:#6a1b9a,stroke-width:2px,color:#4a148c

    class Agent client
    class Tools,Orchestrator,GeoHelpers,POIStore server
    class OverpassC,CSVImporter server
    class Nominatim,Valhalla backend
    class OverpassAPI external
    class POIPVC,OSMData,POISourceFiles store

How a query flows — "Best Western hotels an hour's drive from Nuremberg":

1. The Agent calls find_within(center="Nuremberg", within="1 hour") over MCP/HTTP.

2. Query Orchestrator resolves "Nuremberg" via Nominatim → coordinates.

3. It requests a 60-min isochrone polygon from Valhalla.

4. It tests each POI Store coordinate against the polygon (Geo Helpers).

5. For matches, one Valhalla matrix call returns each hotel's driving duration.

6. Result returned — one Valhalla round trip regardless of POI count.

How ingestion works — populating the cache (one-shot, at deploy time):

1. Agent (or an admin) calls ingest_poi(source="overpass").

2. Overpass Client sends one Overpass QL query to the Overpass API.

3. Returned OSM hotels (coordinates ready-made) are written to the POI Store → POI Data PVC.

4. Thereafter, find_within reads only from the cache — zero Overpass dependency at query time.

The maps server is the single home for everything geo. The POI cache is persisted on a PVC at /app/data/poi. Overpass is only contacted at ingest time (a one-shot cache-fill); find_within reads the cache at query time with zero Overpass dependency.

POI population: Overpass vs geocoded import

There are two ways to populate the POI collection, and the choice matters for data coverage:

Option 1: Overpass (from OpenStreetMap)

ingest_poi(source="overpass", brand="Best Western", area="around:50000,48.13,11.58")

Queries OpenStreetMap for every feature tagged brand=Best Western in the given area. Coordinates come ready-made from OSM (no geocoding needed).

Limitation: OSM coverage varies by region. In well-mapped areas (Germany) this works well, but poorly-mapped areas (parts of Austria, Switzerland) return incomplete results. For example, a 50 km radius around Lindau (Bodensee) returns only 2 hotels from Overpass, even though 3 Best Westerns exist within that range — the Feldkirch (Austria) hotel is simply not tagged in OSM.

Option 2: Geocoded import (from scraped address data) — recommended for Best Western

ingest_poi(source="json:/path/to/hotels_geocoded.json", replace=True)

Imports a pre-built JSON file of hotels with coordinates obtained by geocoding the scraped address data (street + postal code + city) via Nominatim. This bypasses OSM gaps entirely because every hotel in the scraped corpus gets a coordinate, regardless of whether OSM knows about it.

How the geocoded file is built:

1. The scraper (/home/rannox/bwh/enrich_hotels.py) produces hotel_data.jsonl — 178 hotels with structured addresses (street, postal_code, city, phone_country_code).

2. The geocoding script (/home/rannox/bwh/geocode_hotels.py) reads each address, queries Nominatim, and writes hotels_geocoded.json — a list of {name, lat, lon, street, postcode, city, country, brand} objects in the JSON import format.

3. The self-hosted Nominatim (nominatim.geo.svc.cluster.local:8080) only has Germany data (built from a DE PBF extract). For hotels in Austria (AT) and Switzerland (CH), the script falls back to the public Nominatim (nominatim.openstreetmap.org) with a country suffix for disambiguation.

4. The resulting JSON file is imported via ingest_poi(source="json:...", replace=True) into the POI collection on the PVC (/app/data/poi/bestwestern-de.json).

To rebuild and reimport (e.g., after a new scrape):

# 1. Geocode all hotels (run from inside the maps-mcp pod, or any pod
#    with network access to the Nominatim service)
python3 /home/rannox/bwh/geocode_hotels.py \
  --input /home/rannox/bwh/hotel_data.jsonl \
  --output /home/rannox/bwh/hotels_geocoded.json

# 2. Copy the JSON file into the pod
kubectl -n jq-mcp-servers cp /home/rannox/bwh/hotels_geocoded.json \
  maps-mcp-server-XXX:/tmp/hotels_geocoded.json

# 3. Import via the tool (direct Python call, bypasses MCP transport)
kubectl -n jq-mcp-servers exec deploy/maps-mcp-server -- uv run python -c "
import asyncio
from src.server import ingest_poi
asyncio.run(ingest_poi(
    source='json:/tmp/hotels_geocoded.json',
    collection='bestwestern-de',
    replace=True
))
"

# 4. Verify
kubectl -n jq-mcp-servers exec deploy/maps-mcp-server -- uv run python -c "
from src.server import poi_store
print(len(poi_store.load('bestwestern-de')), 'POIs')
"

Coverage: 164 of 178 hotels geocoded successfully. The 14 failures are mostly hotels with non-standard addresses (e.g., ipartment branded properties without a clear street address, or newly opened hotels not yet in Nominatim). These can be manually geocoded and appended if needed.

Which to use?

For the Best Western agent flow (hotels + RAG capacity queries), the geocoded import is the recommended approach because it guarantees every hotel in the RAG corpus is findable by distance — including Austrian and Swiss hotels that OSM doesn't have.

The 9 MCP tools

Full tool documentation is in jquad-ai-assistant-agent/skills/maps/SKILL.md.

How find_within works (the key correctness point)

The within string decides the operation:

• Distance ("50 km", "30 miles"): one Valhalla sources_to_targets call (road distance — what users mean). metric="crow" falls back to great-circle haversine.

• Time ("1 hour", "45 min"): one Valhalla isochrone polygon + point-in-polygon membership, plus a matrix call so each match also reports its actual driving duration.

Every query costs at most one Valhalla round trip (plus optionally one isochrone), regardless of how many POIs are evaluated.

Quick start (local dev)

# 1. Install deps
uv sync

# 2. Run tests (no network needed — httpx is mocked)
uv run pytest

# 3. Boot the server (backends unreachable in dev, but tools are live)
OTEL_SDK_DISABLED=true uv run python -m src.server
# → http://127.0.0.1:8000/mcp

For full local functionality you need Valhalla + Nominatim running. The easiest way is the official docker images:

# Valhalla — download Germany extract, build tiles (one-time, ~20 min)
docker run -d --name valhalla -p 8002:8002 \
  -v $(pwd)/valhalla-data:/data/valhalla \
  -e serve_tiles=true gisops/valhalla:latest
# Inside the container:
#   wget -O /data/valhalla/germany-latest.osm.pbf \
#     https://download.geofabrik.de/europe/germany-latest.osm.pbf
# Valhalla rebuilds tiles on next start.

# Nominatim — imports Germany on first boot (~30-60 min)
docker run -d --name nominatim -p 8080:8080 \
  -e PBF_URL=https://download.geofabrik.de/europe/germany-latest.osm.pbf \
  -v $(pwd)/nominatim-data:/var/lib/postgresql/14/main \
  mediagis/nominatim:4.3

Then point the server at them:

export VALHALLA_URL=http://localhost:8002
export NOMINATIM_URL=http://localhost:8080
uv run python -m src.server

Configuration

All config is via environment variables (read once at startup by MapsSettings.from_env()):

How to call the MCP server directly

The MCP protocol requires a Streamable HTTP handshake. Example:

# 1. Initialize session
INIT=$(curl -s -D /tmp/h -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":"init"}')
SID=$(grep -i mcp-session-id /tmp/h | tr -d '\r' | awk '{print $2}')

# 2. Call a tool (geocode Nuremberg)
curl -s -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: $SID" \
  -d '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"geocode","arguments":{"query":"Nuremberg"}},"id":"1"}'

End-to-end: the headline query

After deploying and ingesting the hotel set:

# 1. Ingest (one-time / on refresh) — Best Western, all of Europe, from OSM
#    tools/call ingest_poi {source: "overpass"}
# → {"source": "overpass", "collection": "bestwestern-de", "ingested": 180, "total": 180}

# 2. Ask: Best Western within 1 hour of Nuremberg
#    tools/call find_within {center: "Nuremberg", within: "1 hour"}

The server:

1. Geocodes "Nuremberg" → 49.4521, 11.0767 (Nominatim).

2. Requests a 60-minute isochrone polygon around it (Valhalla).

3. Tests each cached hotel coordinate against the polygon (point-in-polygon).

4. For each hotel inside, calls the Valhalla matrix for its actual driving duration (so it can say "43 min away", not just "inside the zone").

5. Returns the matches sorted shortest-duration-first.

{
  "budget": {"kind": "time", "human": "1 hour", "raw": "1 hour"},
  "center": {"lat": 49.4521, "lon": 11.0767, "display_name": "Nürnberg, Bayern, Germany"},
  "matches": [
    {
      "name": "Best Western Premier Nürnberg City Center",
      "address": "...",
      "lat": 49.45, "lon": 11.07,
      "time_seconds": 600, "time_minutes": 10.0,
      "inside_isochrone": true,
      "source_url": "osm://node:12345"
    }
  ],
  "match_count": 1,
  "total_evaluated": 180
}

(Exact match counts and durations depend on real OSM data and driving times at query time.)

POI ingestion pipeline

The ingest_poi tool loads hotels from one of two sources:

OpenStreetMap via Overpass (default)

ingest_poi(source="overpass", brand="Best Western", area="europe"):

1. Builds an Overpass QL query for every feature tagged brand~"Best Western" inside the area (Europe bbox by default).

2. Sends one POST to the Overpass endpoint.

3. Parses each returned element into a POI with coordinates already attached (no geocoding step — OSM nodes carry lat/lon).

4. Extracts optional addr:*, phone, website, brand, stars tags.

5. Upserts into <collection>.json keyed by sha1(osm_type:osm_id) — idempotent, so re-fetching updates records in place.

The public Overpass instances are rate-limited, so treat ingest as a one-shot cache-fill at deploy time, not a per-query call. For steady traffic, self-host Overpass and point OVERPASS_URL at it.

Curated CSV / JSON file

ingest_poi(source="csv:/app/data/hotels.csv"):

name,lat,lon,street,housenumber,postcode,city,country,phone,website,brand
Best Western Premier Nürnberg City Center,49.4521,11.0767,Koenigstr.,33,90402,Nuremberg,DE,+49 911 206890,https://...,Best Western

CSV headers are case-insensitive; only name,lat,lon are required. Use this to curate a checked-in list, or to supplement OSM where coverage is thin. A JSON file (a list of objects with the same keys) is also accepted.

Re-running ingest_poi updates existing entries; it never duplicates.

Deployment (Kubernetes)

# Build + push (from jquad-ai-assistant-agent/deployment/scripts/)
./build-and-push-all.sh --project jquad-agent-maps-mcp-server

# Deploy to the teams namespace
kubectl apply -k k8s/overlays/teams

One-time data setup (Valhalla + Nominatim)

Both backends need an OSM extract. On first boot:

• Valhalla: download the Germany PBF into the valhalla-data PVC, then restart the pod — it builds routing tiles (10-30 min for Germany).

• Nominatim: set PBF_URL in the manifest (already done); the mediagis/nominatim image imports automatically on first boot (30-60 min, ~3-4 GB RAM).

Subsequent restarts are instant (data is on the PVCs). Both backends use the same Germany extract so coordinates are consistent. Switch to the Europe extract later by changing PBF_URL and the Valhalla download.

Populate the hotel cache

After the maps server pod is up, populate the POI cache from OpenStreetMap:

# Via MCP API (from inside the cluster) or a chat request:
ingest_poi(source="overpass", brand="Best Western", area="europe")
# → fetches ~150-200 Best Western hotels across Europe from OSM,
#   caches them on the maps-mcp-poi-data PVC.

This is a one-shot cache-fill. To supplement OSM coverage, also import a curated CSV:

ingest_poi(source="csv:/app/data/hotels.csv")

If you self-host Overpass, set OVERPASS_URL in the configmap first.

Testing

uv run pytest                          # all tests
uv run pytest tests/test_geo.py -v     # spatial helpers only
uv run pytest --cov=src                # with coverage

The test suite (128 tests) covers:

• test_geo.py — haversine, point-in-polygon (with holes), the parse_within budget parser (distance + time + edge cases).

• test_poi_store.py — JSON cache upsert/dedup/delete, UTF-8, path sanitization (no traversal).

• test_overpass_client.py — Overpass QL query builder (Europe bbox, country codes, brand regex widening), element parsing (node + way center, dedup, unnamed-skip), httpx wire format mocked via respx including rate-limit (429) and gateway-timeout (504) handling.

• test_csv_importer.py — CSV/JSON import (case-insensitive headers, BOM, TSV, coordinate validation, missing-column errors), the overpass_to_poi converter, and the import_file extension dispatcher.

• test_nominatim_client.py / test_valhalla_client.py — httpx wire format mocked via respx.

• test_query_orchestrator.py — the find_within spatial filtering for both distance and time budgets, with matrix chunking and isochrone polygon membership.

Related components

License

Copyright © 2025 JQuad. All rights reserved.