openstreetmap-mcp-server

Find OSM features within a bounding box

openstreetmap_query_bbox

Read-onlyIdempotent

Find OSM features within a rectangular geographic area (bounding box) via the Overpass API. Useful for area surveys where you want everything in a region, not proximity searches. Use amenity for common POI types (hospital, pharmacy, cafe, school, etc.) or tag_key + tag_value for other OSM categories (leisure=park, shop=supermarket, natural=peak). Exactly one of amenity or tag_key/tag_value must be provided. Every feature includes its full OSM tag set; the extratags flag (used by the Nominatim-backed openstreetmap_search_places, openstreetmap_reverse_geocode, and openstreetmap_lookup_objects tools) does not apply here. For proximity searches centered on a point, use openstreetmap_query_nearby instead.

Input Schema

TableJSON Schema

Name	Required	Description
`east`	Yes	Eastern boundary longitude (maximum longitude). A value below west describes an antimeridian crossing rather than an inverted box.
`west`	Yes	Western boundary longitude (minimum longitude). A west greater than east is valid, not an error: Overpass reads it as an antimeridian-crossing box and returns the union of west..180 and -180..east.
`limit`	No	Maximum results to return. Applied after the Overpass query — if the area has more features, they are truncated.
`north`	Yes	Northern boundary latitude (maximum latitude).
`south`	Yes	Southern boundary latitude (minimum latitude).
`offset`	No	Number of matching features to skip before applying limit, for paging through a large result set. The full match set is fetched and cached ~10 minutes keyed by the query, so re-paging at a new offset is deterministic and costs no extra upstream request. Pass the nextOffset value from a prior truncated response.
`amenity`	No	OSM amenity tag value shortcut (e.g., "cafe", "bench", "hospital"). Cannot be combined with tag_key/tag_value.
`tag_key`	No	OSM tag key for non-amenity queries (e.g., "leisure", "shop", "natural"). Use with tag_value. Cannot be combined with amenity.
`tag_value`	No	OSM tag value paired with tag_key (e.g., "park", "supermarket", "peak").
`element_types`	No	OSM element types to search, at least one. Ways cover most buildings and areas; nodes cover most standalone POIs. Add "relation" for complex structures. Omit the field to search nodes and ways; an empty array is rejected because it can only match nothing.
`timeout_seconds`	No	Overpass query timeout in seconds. Increase for large bounding boxes or dense areas.

Output Schema

TableJSON Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`notice`	No	Guidance when the page came back empty. Distinguishes a query that matched nothing (try a different bounding box or tag) from an offset past the end of a non-empty result set (retry at a lower offset). Absent when results were returned.
`elements`	No	Matching OSM features within the bounding box, up to the limit.
`truncated`	No	True if results were cut at the limit. Reduce bbox area, add more specific tags, or page with offset to retrieve the rest.
`nextOffset`	No	Offset to pass on the next call to retrieve the following page of features. Present only when more features remain beyond this page.
`totalFound`	No	Total features returned by Overpass before limit truncation.
`attribution`	No	Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0.
`effectiveTag`	No	The OSM tag filter applied (key=value, e.g. "amenity=cafe" or "leisure=park").
`data_timestamp`	No	OSM data freshness timestamp from the Overpass response. Absent when the endpoint reported no freshness metadata.
`servingEndpoint`	No	Overpass endpoint that produced this response, as origin and path. Differs from the first configured endpoint when a mirror answered after the primary failed, and names the endpoint that served a cached response rather than the one this call would have tried. Pair it with data_timestamp when a result looks unexpectedly slow, sparse, or stale.

Schema Changelog

Changes observed during successful MCP inspections. Dates show when Glama detected each change.

Changed1 schema field changedSep 3, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_bbox`: The bounding box is inverted on the latitude axis — south is greater than north. `invalid_tag`: Both amenity and tag_key/tag_value are provided, neither is provided, or a tag key/value contains Overpass QL metacharacters. `query_timeout`: The Overpass query exceeded the timeout. `result_too_large`: Overpass ran out of memory — the result set exceeds the server memory limit. `rate_limited`: Overpass refused the query as throttled — HTTP 429, or a throttle document instead of JSON — on every configured endpoint. With a list in OSM_OVERPASS_ENDPOINTS the call advances to the next entry first, so this surfaces only once all of them have refused it. `upstream_error`: Overpass reported a runtime error that is neither a timeout nor memory exhaustion — the message carries the remark verbatim. `overpass_gateway_timeout`: Overpass answered HTTP 504 — it accepted the query but its dispatcher gave up before producing a result, so the query exceeded the time budget the endpoint enforces rather than timeout_seconds. `overpass_unavailable`: Overpass answered with an HTTP 5xx other than 504 (500, 501, 502, 503) — the endpoint is down, restarting, or shedding load. The thrown code tracks the status: 500 and 501 surface as InternalError, every other 5xx as ServiceUnavailable. `endpoints_exhausted`: Every Overpass endpoint tried was still unanswered when the call ran out of its total time budget — each accepted the query and held the connection instead of failing outright. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_bbox`: The bounding box is inverted on the latitude axis — south is greater than north. `invalid_tag`: Both amenity and tag_key/tag_value are provided, neither is provided, or a tag key/value contains Overpass QL metacharacters. `query_timeout`: The Overpass query exceeded the timeout. `result_too_large`: Overpass ran out of memory — the result set exceeds the server memory limit. `rate_limited`: Overpass refused the query as throttled — HTTP 429, or a throttle document instead of JSON — on every configured endpoint. With a list in OSM_OVERPASS_ENDPOINTS the call advances to the next entry first, so this surfaces only once all of them have refused it. `upstream_error`: Overpass reported a runtime error that is neither a timeout nor memory exhaustion — the message carries the remark verbatim. `overpass_gateway_timeout`: Overpass answered HTTP 504 — it accepted the query but its dispatcher gave up before producing a result, so the query exceeded the time budget the endpoint enforces rather than timeout_seconds. `overpass_unavailable`: Overpass answered with an HTTP 5xx other than 504 (500, 501, 502, 503) — the endpoint is down, restarting, or shedding load. Every one of them surfaces as ServiceUnavailable. `endpoints_exhausted`: Every Overpass endpoint tried was still unanswered when the call ran out of its total time budget — each accepted the query and held the connection instead of failing outright. Other values are possible when a failure originates below the handler."

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "elements",
+      "attribution",
+      "effectiveTag",
+      "totalFound",
+      "truncated"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `invalid_bbox`: The bounding box is inverted on the latitude axis — south is greater than north. `invalid_tag`: Both amenity and tag_key/tag_value are provided, neither is provided, or a tag key/value contains Overpass QL metacharacters. `query_timeout`: The Overpass query exceeded the timeout. `result_too_large`: Overpass ran out of memory — the result set exceeds the server memory limit. `rate_limited`: Overpass refused the query as throttled — HTTP 429, or a throttle document instead of JSON — on every configured endpoint. With a list in OSM_OVERPASS_ENDPOINTS the call advances to the next entry first, so this surfaces only once all of them have refused it. `upstream_error`: Overpass reported a runtime error that is neither a timeout nor memory exhaustion — the message carries the remark verbatim. `overpass_gateway_timeout`: Overpass answered HTTP 504 — it accepted the query but its dispatcher gave up before producing a result, so the query exceeded the time budget the endpoint enforces rather than timeout_seconds. `overpass_unavailable`: Overpass answered with an HTTP 5xx other than 504 (500, 501, 502, 503) — the endpoint is down, restarting, or shedding load. The thrown code tracks the status: 500 and 501 surface as InternalError, every other 5xx as ServiceUnavailable. `endpoints_exhausted`: Every Overpass endpoint tried was still unanswered when the call ran out of its total time budget — each accepted the query and held the connection instead of failing outright. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "invalid_bbox",
+            "invalid_tag",
+            "query_timeout",
+            "result_too_large",
+            "rate_limited",
+            "upstream_error",
+            "overpass_gateway_timeout",
+            "overpass_unavailable",
+            "endpoints_exhausted"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "elements",
-  "attribution",
-  "effectiveTag",
-  "totalFound",
-  "truncated"
-]

Changed2 schema fields changedAug 10, 2026

changedInput schema / properties / element_types / description

Previous value: -"OSM element types to search. Ways cover most buildings and areas; nodes cover most standalone POIs. Add \"relation\" for complex structures."New value: +"OSM element types to search, at least one. Ways cover most buildings and areas; nodes cover most standalone POIs. Add \"relation\" for complex structures. Omit the field to search nodes and ways; an empty array is rejected because it can only match nothing."

addedInput schema / properties / element_types / minItems
```
Added value: +1
```

Changed1 schema field changedAug 2, 2026

addedInput schema / anyOf

Added value: +[
+  {
+    "required": [
+      "amenity"
+    ],
+    "type": "object"
+  },
+  {
+    "required": [
+      "tag_key",
+      "tag_value"
+    ],
+    "type": "object"
+  }
+]

Changed1 schema field changedJul 30, 2026

addedOutput schema / properties / servingEndpoint

Added value: +{
+  "description": "Overpass endpoint that produced this response, as origin and path. Differs from the first configured endpoint when a mirror answered after the primary failed, and names the endpoint that served a cached response rather than the one this call would have tried. Pair it with data_timestamp when a result looks unexpectedly slow, sparse, or stale.",
+  "type": "string"
+}

Changed4 schema fields changedJul 30, 2026

changedInput schema / properties / east / description

Previous value: -"Eastern boundary longitude (maximum longitude)."New value: +"Eastern boundary longitude (maximum longitude). A value below west describes an antimeridian crossing rather than an inverted box."

changedInput schema / properties / west / description

Previous value: -"Western boundary longitude (minimum longitude)."New value: +"Western boundary longitude (minimum longitude). A west greater than east is valid, not an error: Overpass reads it as an antimeridian-crossing box and returns the union of west..180 and -180..east."

changedOutput schema / properties / data_timestamp / description

Previous value: -"OSM data freshness timestamp from the Overpass response."New value: +"OSM data freshness timestamp from the Overpass response. Absent when the endpoint reported no freshness metadata."

changedOutput schema / required

Previous value: -[
-  "elements",
-  "data_timestamp",
-  "attribution",
-  "effectiveTag",
-  "totalFound",
-  "truncated"
-]New value: +[
+  "elements",
+  "attribution",
+  "effectiveTag",
+  "totalFound",
+  "truncated"
+]

Changed1 schema field changedJul 26, 2026

changedOutput schema / properties / elements / items / properties / osm_id / description

Previous value: -"OSM element ID. Use with osm_type for openstreetmap_lookup."New value: +"OSM element ID. Use with osm_type for openstreetmap_lookup_objects."

Changed1 schema field changedJul 26, 2026

changedOutput schema / properties / notice / description

Previous value: -"Guidance when no features were found — e.g., try a different bounding box or tag. Absent when results were returned."New value: +"Guidance when the page came back empty. Distinguishes a query that matched nothing (try a different bounding box or tag) from an offset past the end of a non-empty result set (retry at a lower offset). Absent when results were returned."

Changed3 schema fields changedJul 6, 2026

addedInput schema / properties / offset

Added value: +{
+  "default": 0,
+  "description": "Number of matching features to skip before applying limit, for paging through a large result set. The full match set is fetched and cached ~10 minutes keyed by the query, so re-paging at a new offset is deterministic and costs no extra upstream request. Pass the nextOffset value from a prior truncated response.",
+  "maximum": 9007199254740991,
+  "minimum": 0,
+  "type": "integer"
+}

addedOutput schema / properties / nextOffset

Added value: +{
+  "description": "Offset to pass on the next call to retrieve the following page of features. Present only when more features remain beyond this page.",
+  "type": "number"
+}

changedOutput schema / properties / truncated / description

Previous value: -"True if results were cut at the limit. Reduce bbox area or add more specific tags to narrow the result set."New value: +"True if results were cut at the limit. Reduce bbox area, add more specific tags, or page with offset to retrieve the rest."

Changed5 schema fields changedMay 30, 2026

addedOutput schema / properties / effectiveTag

Added value: +{
+  "description": "The OSM tag filter applied (key=value, e.g. \"amenity=cafe\" or \"leisure=park\").",
+  "type": "string"
+}

addedOutput schema / properties / notice

Added value: +{
+  "description": "Guidance when no features were found — e.g., try a different bounding box or tag. Absent when results were returned.",
+  "type": "string"
+}

addedOutput schema / properties / totalFound

Added value: +{
+  "description": "Total features returned by Overpass before limit truncation.",
+  "type": "number"
+}

removedOutput schema / properties / total_found

Removed value: -{
-  "description": "Total features returned by Overpass before limit truncation.",
-  "type": "number"
-}

changedOutput schema / required

Previous value: -[
-  "elements",
-  "total_found",
-  "truncated",
-  "data_timestamp",
-  "attribution"
-]New value: +[
+  "elements",
+  "data_timestamp",
+  "attribution",
+  "effectiveTag",
+  "totalFound",
+  "truncated"
+]

First observedMay 25, 2026

TDQS

A4.9/5.0

Behavior5/5

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

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. The description adds significant behavioral context: antimeridian crossing interpretation for west/east, truncation after limit, offset caching with ~10 minute deterministic paging, default element_types and empty array rejection, and timeout adjustment guidance. It also clarifies that full tag sets are returned and extratags doesn't apply. No contradictions with annotations.

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

Conciseness5/5

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

The description is dense but every sentence adds value. It begins with the core purpose, then usage context, parameter guidance, behavioral notes, and a sibling alternative. There is no filler or repetition of schema content that isn't already needed for clarity. It is well-structured and front-loaded.

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

Completeness5/5

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

Given 11 parameters, a bounding box with antimeridian semantics, and an anyOf constraint, the description covers all critical operational details: antimeridian handling, truncation, paging, element types, timeout, and the extratags distinction from siblings. The output schema exists, so return format doesn't need description. Nothing an agent needs to call this correctly is missing.

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 baseline is 3. The description adds genuine value beyond the schema: it explains the anyOf constraint in plain language, clarifies the antimeridian behavior for west/east (schema also mentions it, but description repeats and reinforces), explains offset caching and deterministic re-paging, and details element_types defaults and empty array rejection. These go beyond what schema descriptions provide, so a 4 is warranted.

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

Purpose5/5

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

States a specific verb and resource ('Find OSM features within a rectangular geographic area via the Overpass API'), explicitly distinguishes from siblings by naming openstreetmap_query_nearby for proximity searches. The description also clarifies that other tools use extratags, further differentiating it. An agent can immediately understand what this tool does and how it differs from related tools.

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

Usage Guidelines5/5

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

Explicitly states when to use the tool ('area surveys where you want everything in a region, not proximity searches') and provides a direct alternative: 'For proximity searches centered on a point, use openstreetmap_query_nearby instead.' It also explains the required parameter combination (exactly one of amenity or tag_key/tag_value) and clarifies which other tools use extratags, leaving no ambiguity about selection.

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

All openstreetmap-mcp-server tools Inspect

Try in Browser

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.9/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: forward geocoding, reverse geocoding, ID-based lookup, bbox queries, nearby radius queries, and raw Overpass queries. Even the two spatial query tools are explicitly differentiated by geometry type.

Naming Consistency5/5

All tools follow the openstreetmap_ verb-based snake_case pattern, with action words like lookup, query, search, and reverse. The three query variants are consistently named with clear qualifiers (bbox, nearby, raw).

Tool Count5/5

Six tools is a well-scoped set for an OpenStreetMap read-only server. Each tool covers a distinct core need without redundancy or padding.

Completeness5/5

The surface covers the major OSM read workflows: geocoding both directions, resolving known IDs, spatial filtering by area or proximity, and a raw escape hatch for advanced queries. No critical lifecycle or query operation is missing for the stated domain.

Find OSM features within a bounding box

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

TDQS

Resources