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)

Need	This server	Google Maps
"an hour away" (isochrone)	✅ native Valhalla isochrone	⚠️ requires distance-matrix hacks
self-hostable, free	✅ both pods in your cluster	❌ paid, external
no per-query cost	✅	❌
POI source	OpenStreetMap (free, community-mapped)	Places API (paid)

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.

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":

The Agent calls find_within(center="Nuremberg", within="1 hour") over MCP/HTTP.
Query Orchestrator resolves "Nuremberg" via Nominatim → coordinates.
It requests a 60-min isochrone polygon from Valhalla.
It tests each POI Store coordinate against the polygon (Geo Helpers).
For matches, one Valhalla matrix call returns each hotel's driving duration.
Result returned — one Valhalla round trip regardless of POI count.

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

Agent (or an admin) calls ingest_poi(source="overpass").
Overpass Client sends one Overpass QL query to the Overpass API.
Returned OSM hotels (coordinates ready-made) are written to the POI Store → POI Data PVC.
Thereafter, find_within reads only from the cache — zero Overpass dependency at query time.

Component	Responsibility
maps-mcp-server	Single home for everything geo. Exposes 9 MCP tools; orchestrates the backends.
Query Orchestrator	The `find_within` brain: decides isochrone-vs-matrix, filters POIs, chunks matrix calls.
Geo Helpers	Pure spatial math (haversine, point-in-polygon, budget parsing). No I/O.
POI Store	JSON cache of geocoded POIs on a PVC. The query path's only data source.
Overpass Client / CSV Importer	Ingest-only adapters that populate the POI Store (not on the query path).
Nominatim	Geocoding: place names → coordinates (Nuremberg → 49.45, 11.08).
Valhalla	Routing: isochrones, routes, time-distance matrices. The "an hour away" engine.
Overpass API	Read-only source of POI coordinates from OpenStreetMap. Contacted only at ingest time.
OSM Extract	The same Germany PBF shared by Nominatim and Valhalla for consistent coordinates.

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:

The scraper (/home/rannox/bwh/enrich_hotels.py) produces hotel_data.jsonl — 178 hotels with structured addresses (street, postal_code, city, phone_country_code).
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.
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.
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?

	Overpass	Geocoded import
Coverage	Depends on OSM quality (gaps in AT/CH)	Complete for all hotels in the scraped corpus
Auto-updates	Reflects live OSM edits	Snapshot — rebuild needed after a new scrape
Coordinate source	OSM (precise to building)	Nominatim geocoding (precise to address)
Brand filtering	Any brand OSM knows	Only brands in the scraped data
Best for	General POI discovery (restaurants, etc.)	Best Western hotel search (the primary use case)

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

Tool	Purpose
`find_within`	Headline tool. POIs within a distance or time budget of a center.
`route`	Point-to-point driving distance + duration.
`distance_matrix`	Batch one-to-many / many-to-many times + distances.
`isochrone`	The "reachable within X minutes" polygon.
`geocode`	Place name / address → coordinates.
`reverse_geocode`	Coordinates → address.
`list_poi`	Dump the ingested POI cache.
`ingest_poi`	Admin: load hotels from OpenStreetMap (Overpass) or a curated file → cache.
`maps_health`	Internal: backend health check.

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()):

Variable	Default	Description
`PORT`	`8000`	HTTP listen port.
`LOG_LEVEL`	`INFO`	Logging level.
`VALHALLA_URL`	`http://valhalla.teams.svc.cluster.local:8002`	Valhalla base URL.
`NOMINATIM_URL`	`http://nominatim.teams.svc.cluster.local:8080`	Nominatim base URL.
`NOMINATIM_RATE_LIMIT_RPS`	`5.0`	Max Nominatim req/sec (1/rps = min interval).
`NOMINATIM_USER_AGENT`	`jquad-maps-mcp`	User-Agent header.
`OVERPASS_URL`	`https://overpass-api.de/api/interpreter`	Overpass endpoint for POI ingest. Self-host or use a paid mirror for production.
`OVERPASS_TIMEOUT`	`90.0`	Per-request Overpass timeout (Europe brand queries can be slow).
`POI_DATA_PATH`	`./data/poi`	Directory for ingested POI JSON caches.
`POI_DEFAULT_COLLECTION`	`bestwestern-de`	Default collection for `find_within` / `list_poi`.
`POI_DEFAULT_BRAND`	`Best Western`	Default brand for `ingest_poi(source="overpass")`.
`POI_DEFAULT_AREA`	`europe`	Default geographic scope for Overpass ingest (`europe`, a country code, a list, or a bbox).
`MAX_MATRIX_SIZE`	`50`	Max destinations per Valhalla matrix call (chunked above this).
`HTTP_TIMEOUT_SECONDS`	`30.0`	Outbound HTTP total timeout.
`HTTP_CONNECT_TIMEOUT`	`10.0`	Outbound connect timeout.
`KEYCLOAK_ENABLED`	`false`	Optional JWT validation (agent forwards token regardless).
`OTEL_EXPORTER_OTLP_ENDPOINT`	(OTel default)	OTLP gRPC endpoint for tracing.
`OTEL_SERVICE_NAME`	`maps-mcp-server`	Service name in traces.

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:

Geocodes "Nuremberg" → 49.4521, 11.0767 (Nominatim).
Requests a 60-minute isochrone polygon around it (Valhalla).
Tests each cached hotel coordinate against the polygon (point-in-polygon).
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").
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"):

Builds an Overpass QL query for every feature tagged brand~"Best Western" inside the area (Europe bbox by default).
Sends one POST to the Overpass endpoint.
Parses each returned element into a POI with coordinates already attached (no geocoding step — OSM nodes carry lat/lon).
Extracts optional addr:*, phone, website, brand, stars tags.
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

Component	Role
jquad-ai-assistant-agent	Orchestrator; consumes this server via `skills/maps/SKILL.md`.
OpenStreetMap / Overpass	Source of POI data (Best Western hotels) — coordinates ready-made, no geocoding needed.
jq-rag-mcp / web-search-discovery / web-crawler	Sibling MCP servers sharing the same FastMCP pattern.

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
data/poi		data/poi
helm		helm
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Repository files navigation

Maps MCP Server

Why these backends (and not Google Maps)

Architecture

POI population: Overpass vs geocoded import

Option 1: Overpass (from OpenStreetMap)

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

Which to use?

The 9 MCP tools

How `find_within` works (the key correctness point)

Quick start (local dev)

Configuration

How to call the MCP server directly

End-to-end: the headline query

POI ingestion pipeline

OpenStreetMap via Overpass (default)

Curated CSV / JSON file

Deployment (Kubernetes)

One-time data setup (Valhalla + Nominatim)

Populate the hotel cache

Testing

Related components

License

About

Releases

Packages

Contributors

Languages

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

Maps MCP Server

Why these backends (and not Google Maps)

Architecture

POI population: Overpass vs geocoded import

Option 1: Overpass (from OpenStreetMap)

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

Which to use?

The 9 MCP tools

How find_within works (the key correctness point)

Quick start (local dev)

Configuration

How to call the MCP server directly

End-to-end: the headline query

POI ingestion pipeline

OpenStreetMap via Overpass (default)

Curated CSV / JSON file

Deployment (Kubernetes)

One-time data setup (Valhalla + Nominatim)

Populate the hotel cache

Testing

Related components

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

How `find_within` works (the key correctness point)