bbox-mcp-server

search_overpass

Read-onlyIdempotent

Run Overpass QL queries to find OpenStreetMap POIs, roads, and amenities inside an admin boundary, bounding box, or radius, returning filtered, structured results with map links.

Instructions

Execute an Overpass QL query to find POIs, roads, or other OSM features within an admin boundary area, bounding box, or radius. The server wraps your query in spatial filters, detects Overpass runtime errors, and returns structured JSON with provenance, completeness metadata, distance calculations, and a map link.

SEARCH MODES:

Location / Admin Area: when 'location' resolves to an OSM boundary polygon (e.g. 'Manhattan', 'Seattle'), searches inside exact boundary polygon.
Bounding box (default): searches a rectangular area.
Circle: searches within an exact radius when 'radius_meters' is provided.
Fast Count: set 'count_only: true' to get instant element counts without downloading full element payloads.

COMMON TAG EXAMPLES:

Restaurants: nwr["amenity"="restaurant"]
Pizza: nwr["amenity"="fast_food"]["cuisine"="pizza"]
Supermarkets: nwr["shop"="supermarket"]
Parks: nwr["leisure"="park"]
Hospitals: nwr["amenity"="hospital"]
EV Charging: nwr["amenity"="charging_station"]
Gyms: nwr["leisure"="fitness_centre"]
Banks: nwr["amenity"="bank"]

Input Schema

Name	Required	Description
`bbox`	No	The geometry to parse. Can be a raw bounding box string ('lat1,lng1,lat2,lng2'), WKT, GeoJSON, or ogrinfo extent. Either 'location' or 'bbox' MUST be provided.
`limit`	No	Maximum number of elements to return per page. Default is 100.
`query`	Yes	The Overpass QL core query. Example: `node["amenity"="cafe"]` or `nwr["leisure"="park"]`. Multi-statement queries supported (e.g. `nwr["office"="coworking"]; nwr["amenity"="coworking_space"]`). DO NOT include spatial filters or output directives.
`offset`	No	Pagination offset for retrieving subsequent pages of results. Default is 0.
`location`	No	A text location to search for (e.g. 'Manhattan', 'San Francisco'). Either 'location' or 'bbox' MUST be provided.
`count_only`	No	If true, executes an ultra-fast Overpass 'out count;' query and returns total counts (nodes, ways, relations, total) without downloading individual features. Defaults to false.
`radius_meters`	No	Search radius in metres. Enables circle mode — use ONLY when explicit distance is specified ('2km' → 2000).
`return_geometry`	No	If true, returns full geometry (polygon/polyline) for ways and relations instead of center point. Defaults to false.
`timeout_seconds`	No	Overpass server query timeout in seconds. Default is 25.
`sort_by_distance`	No	If true, sorts returned elements by distance from origin/center. Enabled by default for circle mode and point locations.
`use_area_boundary`	No	If true (default), uses exact OSM administrative boundary polygon for named locations when available, avoiding bounding box collapse.

Output Schema

Name	Required	Description	Default
`limit`	No
`osm3s`	No
`counts`	No
`offset`	No
`complete`	Yes
`elements`	No
`has_more`	No
`warnings`	Yes
`generator`	No
`share_url`	Yes
`truncated`	No
`count_only`	Yes
`provenance`	Yes
`next_offset`	No
`osm_area_id`	No
`search_mode`	Yes
`total_count`	No
`alternatives`	No
`distance_from`	No
`matched_place`	No
`returned_count`	No
`pagination_hint`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed11 schema fields changedv1.5.0Nov 4, 2026

addedInput schema / properties / count_only

Added value: +{
+  "description": "If true, executes an ultra-fast Overpass 'out count;' query and returns total counts (nodes, ways, relations, total) without downloading individual features. Defaults to false.",
+  "type": "boolean"
+}

changedInput schema / properties / limit / description

Previous value: -"Maximum number of elements to return. Default is 100. Increase if you need more results."New value: +"Maximum number of elements to return per page. Default is 100."

changedInput schema / properties / location / description

Previous value: -"A text location to search for (e.g. 'San Francisco', 'JFK Airport'). Requires MAPBOX_ACCESS_TOKEN env var. Either 'location' or 'bbox' MUST be provided."New value: +"A text location to search for (e.g. 'Manhattan', 'San Francisco'). Either 'location' or 'bbox' MUST be provided."

addedInput schema / properties / offset

Added value: +{
+  "description": "Pagination offset for retrieving subsequent pages of results. Default is 0.",
+  "type": "number"
+}

changedInput schema / properties / query / description

Previous value: -"The Overpass QL core query. Example: `node[\"amenity\"=\"cafe\"]` or `nwr[\"leisure\"=\"park\"]`. DO NOT include spatial filters, bounding box, or output directives — the server handles those automatically."New value: +"The Overpass QL core query. Example: `node[\"amenity\"=\"cafe\"]` or `nwr[\"leisure\"=\"park\"]`. Multi-statement queries supported (e.g. `nwr[\"office\"=\"coworking\"]; nwr[\"amenity\"=\"coworking_space\"]`). DO NOT include spatial filters or output directives."

changedInput schema / properties / radius_meters / description

Previous value: -"Search radius in metres. Enables circle mode — use ONLY when the user specifies an explicit distance (e.g. '2km' → 2000, '500 metres' → 500, '1 mile' → 1609). Omit entirely for area/region queries or vague terms like 'near'."New value: +"Search radius in metres. Enables circle mode — use ONLY when explicit distance is specified ('2km' → 2000)."

addedInput schema / properties / return_geometry

Added value: +{
+  "description": "If true, returns full geometry (polygon/polyline) for ways and relations instead of center point. Defaults to false.",
+  "type": "boolean"
+}

addedInput schema / properties / sort_by_distance

Added value: +{
+  "description": "If true, sorts returned elements by distance from origin/center. Enabled by default for circle mode and point locations.",
+  "type": "boolean"
+}

addedInput schema / properties / timeout_seconds

Added value: +{
+  "description": "Overpass server query timeout in seconds. Default is 25.",
+  "type": "number"
+}

addedInput schema / properties / use_area_boundary

Added value: +{
+  "description": "If true (default), uses exact OSM administrative boundary polygon for named locations when available, avoiding bounding box collapse.",
+  "type": "boolean"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "alternatives": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "complete": {
+      "type": "boolean"
+    },
+    "count_only": {
+      "type": "boolean"
+    },
+    "counts": {
+      "properties": {
+        "nodes": {
+          "type": "number"
+        },
+        "relations": {
+          "type": "number"
+        },
+        "total": {
+          "type": "number"
+        },
+        "ways": {
+          "type": "number"
+        }
+      },
+      "type": "object"
+    },
+    "distance_from": {
+      "type": "object"
+    },
+    "elements": {
+      "items": {
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "generator": {
+      "type": "string"
+    },
+    "has_more": {
+      "type": "boolean"
+    },
+    "limit": {
+      "type": "number"
+    },
+    "matched_place": {
+      "type": "string"
+    },
+    "next_offset": {
+      "type": "number"
+    },
+    "offset": {
+      "type": "number"
+    },
+    "osm3s": {
+      "type": "object"
+    },
+    "osm_area_id": {
+      "type": "number"
+    },
+    "pagination_hint": {
+      "type": "string"
+    },
+    "provenance": {
+      "properties": {
+        "attribution": {
+          "type": "string"
+        },
+        "cache_age_ms": {
+          "type": "number"
+        },
+        "cached": {
+          "type": "boolean"
+        },
+        "data_timestamp": {
+          "type": "string"
+        },
+        "provider": {
+          "type": "string"
+        },
+        "usage_policy": {
+          "type": "string"
+        }
+      },
+      "required": [
+        "provider",
+        "data_timestamp",
+        "cached",
+        "cache_age_ms"
+      ],
+      "type": "object"
+    },
+    "returned_count": {
+      "type": "number"
+    },
+    "search_mode": {
+      "type": "string"
+    },
+    "share_url": {
+      "type": "string"
+    },
+    "total_count": {
+      "type": "number"
+    },
+    "truncated": {
+      "type": "boolean"
+    },
+    "warnings": {
+      "items": {
+        "type": "string"
+      },
+      "type": "array"
+    }
+  },
+  "required": [
+    "search_mode",
+    "count_only",
+    "share_url",
+    "provenance",
+    "complete",
+    "warnings"
+  ],
+  "type": "object"
+}

Changed4 schema fields changedv1.2.5May 7, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum number of elements to return. Helps prevent enormous JSON responses. Default is 100. Set to a higher number if you need more results."New value: +"Maximum number of elements to return. Default is 100. Increase if you need more results."

changedInput schema / properties / location / description

Previous value: -"A text location to search for (e.g. 'San Francisco'). Requires MAPBOX_ACCESS_TOKEN env var. Either 'location' or 'bbox' MUST be provided."New value: +"A text location to search for (e.g. 'San Francisco', 'JFK Airport'). Requires MAPBOX_ACCESS_TOKEN env var. Either 'location' or 'bbox' MUST be provided."

changedInput schema / properties / query / description

Previous value: -"The Overpass QL core query. Example: `node[\"amenity\"=\"cafe\"]` or `nwr[\"leisure\"=\"park\"]`. DO NOT include the bounding box `(S,W,N,E)` or output format (`out json`), the server handles that automatically."New value: +"The Overpass QL core query. Example: `node[\"amenity\"=\"cafe\"]` or `nwr[\"leisure\"=\"park\"]`. DO NOT include spatial filters, bounding box, or output directives — the server handles those automatically."

addedInput schema / properties / radius_meters

Added value: +{
+  "description": "Search radius in metres. Enables circle mode — use ONLY when the user specifies an explicit distance (e.g. '2km' → 2000, '500 metres' → 500, '1 mile' → 1609). Omit entirely for area/region queries or vague terms like 'near'.",
+  "type": "number"
+}

First observedv1.2.4Apr 2, 2026

TDQS

A4.2/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/openWorld/non-destructive, yet the description still adds substantive behavior: the server wraps the query in spatial filters, detects Overpass runtime errors, and returns provenance, completeness metadata, distance calculations, and a map link. The note that the query is auto-wrapped with spatial filters materially changes how an agent should construct input.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and scope, then organized under two clear headers, with no filler sentences. The eight common tag examples are useful for syntax learning but become repetitive after the first three, which all follow the same nwr["key"="value"] pattern.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, open-world query tool with a full output schema and complete annotation coverage, this is close to complete: modes, query construction rules, count fast-path, and return content are all covered. Minor gaps remain around pagination behavior across pages and what a partial/failed query looks like to the caller.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: the 'DO NOT include spatial filters or output directives' constraint on query, the '2km → 2000' unit interpretation for radius_meters, and the note that sort_by_distance is on by default for circle mode and point locations. The tag examples also teach valid Overpass QL syntax that the schema only gestures at.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence gives a specific verb and resource ('Execute an Overpass QL query to find POIs, roads, or other OSM features') plus the three supported spatial scopes. It is unambiguous what the tool does, but it never explicitly distinguishes itself from the closest sibling, aggregate_overpass_h3, which presumably wraps the same data source for H3 aggregation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The SEARCH MODES block gives clear conditional routing among location, bbox, circle, and count_only, and radius_meters carries an explicit 'use ONLY when explicit distance is specified' exclusion. What is missing is any guidance on when to prefer a sibling tool (e.g. aggregate_overpass_h3 for aggregation, list_osm_tags for tag discovery) over this raw search.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server