Tools

6 tools for geocoding and spatial queries against OpenStreetMap data:

openstreetmap_search_places

Convert a place name or address to geographic coordinates via Nominatim/OpenStreetMap.

• Two input modes: free-form query string (e.g., "Space Needle Seattle") or structured address fields (street, city, state, country, postal code) — mutually exclusive
• Country filtering via ISO 3166-1 alpha-2 codes (countrycodes)
• Data layer filtering: address, poi, railway, natural, manmade
• Feature type restriction: country, state, city, settlement
• Optional extra OSM tags on the matched object — contact and metadata (phone, website, opening_hours, wikidata) plus physical attributes (surface, sac_scale, ele, access)
• Preferred language override via BCP 47 code
• Returns results ordered by Nominatim importance score (global prominence)
• Results include coordinates, structured address, bounding box, OSM type/ID for chaining into openstreetmap_lookup_objects
• Matches on name and address relevance, never on an OSM attribute tag — extratags decorates the matched object and cannot select one, so an absent tag describes that object rather than OpenStreetMap. Selecting or enumerating by tag is Overpass-only (openstreetmap_query_nearby, openstreetmap_query_bbox, openstreetmap_query_raw)

openstreetmap_reverse_geocode

Convert latitude/longitude to the nearest address or named place.

• Zoom-level control for address detail: 18=building, 16=street, 14=neighbourhood, 12=town, 10=city, 8=county, 5=state, 3=country
• Layer filtering for matched OSM object type
• Optional extra OSM tags (contact, metadata, and physical attributes) and language preference
• Returns structured address breakdown, OSM type/ID, and bounding box
• Matches on proximity and layer, never on an OSM attribute tag — extratags decorates the matched object and cannot select one. To find the objects in an area carrying a given tag, use openstreetmap_query_nearby, openstreetmap_query_bbox, or openstreetmap_query_raw

openstreetmap_lookup_objects

Fetch full Nominatim address records for known OSM object IDs.

• Accepts an array of up to 50 IDs; a single ID is passed wrapped, e.g. ["N240109189"]
• IDs must be prefixed with N (node), W (way), or R (relation): e.g., "N240109189", "W50637691", "R146656"
• Efficient alternative to a full geocoding round-trip when OSM IDs are already known (e.g., from an Overpass result)
• Reports not_found list for IDs that returned no result
• Optional extra OSM tags (contact, metadata, and physical attributes) and language preference
• Returns exactly the objects named in osm_ids — extratags decorates them and cannot select them. Discover objects by tag with openstreetmap_query_nearby, openstreetmap_query_bbox, or openstreetmap_query_raw, then pass their IDs here

openstreetmap_query_nearby

Find OSM features within a radius around a point via the Overpass API.

• Primary tool for "what's near X?" spatial queries
• Supports amenity shortcut for common POI types (hospital, pharmacy, restaurant, cafe, school, atm) or tag_key + tag_value for any OSM category (leisure=park, shop=supermarket, natural=peak)
• Configurable radius up to 50km; keep under 5km for dense urban POI queries
• Element type filtering: node (standalone POIs), way (buildings/areas), relation (complex structures)
• Limit up to 500 results; truncated flag signals when more exist
• Returns OSM type/ID, coordinates, name, and full tag set for each feature

openstreetmap_query_bbox

Find OSM features within a rectangular geographic bounding box.

• Useful for area surveys where proximity to a single point isn't the goal
• Same amenity / tag_key + tag_value interface as openstreetmap_query_nearby
• A west greater than east is a box crossing the antimeridian, covering west..180 plus -180..east; only south greater than north is rejected
• Configurable timeout for large bounding boxes or dense areas
• Limit up to 500 results with truncated flag

openstreetmap_query_raw

Execute arbitrary Overpass QL for queries the convenience tools don't cover.

• Full Overpass QL expressiveness: multi-type queries, union queries, relation membership, historical queries
• Query must include [out:json]; server injects [timeout:N] if absent
• Returns raw element array — structure varies by query type (nodes have lat/lon, ways have nodes[], relations have members[])
• Limit up to 500 elements per call with totalFound / truncated / nextOffset disclosure; page the rest with offset
• timeout_seconds up to 180 is honored client-side, so a long-running query is not cut off early
• Validate complex queries at overpass-turbo.eu before use

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• Runs locally (stdio/HTTP) or on Cloudflare Workers from the same codebase

Nominatim/Overpass-specific:

• Nominatim usage policy compliance: configurable User-Agent via OSM_USER_AGENT, rate-limit-aware request handling
• Overpass slot budget respected client-side: concurrent submissions capped by OSM_OVERPASS_MAX_CONCURRENCY, and a throttled endpoint is never re-submitted to — the call advances to the next endpoint instead, and fails only once every one has refused it
• Opt-in Overpass endpoint failover: list mirrors in OSM_OVERPASS_ENDPOINTS and a transient failure advances to the next one inside the same call. Deterministic failures (malformed query, result too large) stay on one endpoint, and every response reports the endpoint that served it
• OSM attribution on every response (Data © OpenStreetMap contributors, ODbL 1.0)
• Private instance support — override OSM_NOMINATIM_BASE_URL and OSM_OVERPASS_BASE_URL for self-hosted or mirror endpoints
• Structured error contracts: no_results, no_coverage, conflicting_query_mode, missing_query_mode, invalid_id_format, invalid_tag, invalid_bbox, query_timeout, rate_limited, upstream_error, query_error, result_too_large, overpass_gateway_timeout, overpass_unavailable, endpoints_exhausted — all with actionable recovery hints
• Overpass rejections carry the upstream cause: the whole error document is captured, so an Overpass 5xx surfaces its runtime error: ... remark on every Overpass tool, and a malformed openstreetmap_query_raw query its line N: parse error: ... detail, instead of a bare status

Agent-friendly output: