Skip to main content
Glama

openstreetmap-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Look up address details for OSM objects by ID

openstreetmap_lookup_objects
Read-onlyIdempotent

Fetch the Nominatim address record for up to 50 known OSM objects by ID, each prefixed N (node), W (way), or R (relation), e.g. "N240109189". Use it for IDs already in hand from openstreetmap_query_nearby or openstreetmap_query_bbox; it returns only objects named in osm_ids, listing any that resolve to nothing under not_found, and cannot select by tag, so discover objects with those tools or openstreetmap_query_raw first.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
osm_idsYesOSM IDs to look up, each prefixed with N (node), W (way), or R (relation). Always an array, including for a single ID: ["N240109189"], ["W50637691", "R146656"]. Up to 50 IDs per call.
languageNoPreferred language for names (BCP 47 code).
extratagsNoInclude each looked-up object's extra OSM tags — contact and metadata (phone, website, opening_hours, wikidata) and physical attributes (surface, tracktype, sac_scale, ele, access). An absent tag describes that object, not OpenStreetMap.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
totalNoNumber of results returned.
resultsNoAddress details for the requested OSM IDs that were found.
not_foundNoOSM IDs from the request that returned no result.
attributionNoRequired data attribution: Data © OpenStreetMap contributors, ODbL 1.0.
tagSelectionCaveatNoStanding caveat: tag-based selection lives on the Overpass tools (openstreetmap_query_nearby, openstreetmap_query_bbox, openstreetmap_query_raw), never here. extratags decorates the returned objects rather than selecting them, so a missing tag is not evidence the tag is missing from OpenStreetMap. Present when extratags was requested.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changed
    • changedOutput schema / properties / results / items / properties / boundingbox / description
      Previous value: -"Bounding box as [south, north, west, east] strings."New value: +"Bounding box as [south, north, west, east] in WGS84 decimal degrees."
    • changedOutput schema / properties / results / items / properties / boundingbox / prefixItems
      Previous value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "string"
-  }
-]New value: +[
+  {
+    "type": "number"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "number"
+  },
+  {
+    "type": "number"
+  }
+]
    • changedOutput schema / properties / results / items / properties / lat / description
      Previous value: -"Latitude (WGS84, as string from API)."New value: +"Latitude in WGS84 decimal degrees."
    • changedOutput schema / properties / results / items / properties / lat / type
      Previous value: -"string"New value: +"number"
    • changedOutput schema / properties / results / items / properties / lon / description
      Previous value: -"Longitude (WGS84, as string from API)."New value: +"Longitude in WGS84 decimal degrees."
    • changedOutput schema / properties / results / items / properties / lon / type
      Previous value: -"string"New value: +"number"
    • changedOutput schema / properties / results / items / properties / osm_id / description
      Previous value: -"OSM object ID."New value: +"OSM object ID. Pass \"R\"/\"W\" + this id as within on openstreetmap_query_bbox to search inside this boundary. The same scope in openstreetmap_query_raw is rel(<osm_id>);map_to_area->.a; or way(<osm_id>);map_to_area->.a; then (area.a) on each statement."
  2. Changed2 schema fields changed
    • changedInput schema / properties / extratags / description
      Previous value: -"Include the extra OSM tags each looked-up object carries — contact and metadata tags (phone, website, opening_hours, wikidata) and physical attribute tags alike (surface, tracktype, sac_scale, ele, access). Reports whatever the object happens to carry, so an absent tag describes that object rather than OpenStreetMap."New value: +"Include each looked-up object's extra OSM tags — contact and metadata (phone, website, opening_hours, wikidata) and physical attributes (surface, tracktype, sac_scale, ele, access). An absent tag describes that object, not OpenStreetMap."
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_id_format`: An array element is not a single N/W/R-prefixed OSM ID. `invalid_parameters`: Nominatim returned HTTP 400 — it refused one of the forwarded parameters. Its own message names the parameter and is carried in this error. `rate_limited`: Nominatim returned HTTP 429, or answered HTTP 200 with a throttle document instead of JSON — the one request per second usage policy was exceeded. `upstream_error`: Nominatim returned an unexpected non-2xx status other than 429, or answered HTTP 200 with a body that is not JSON and carries no throttle signature. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_id_format`: An array element is not a single N/W/R-prefixed OSM ID. `invalid_parameters`: Nominatim returned HTTP 400, refusing one of the forwarded parameters; its own message names which one. `rate_limited`: Nominatim returned HTTP 429, or HTTP 200 with a throttle document in place of JSON — the one request per second policy was exceeded. `upstream_error`: Nominatim returned a non-2xx status other than 429, or HTTP 200 with a non-JSON body carrying no throttle signature. Other values are possible when a failure originates below the handler."
  3. Changed2 schema fields changed
    • changedOutput schema / properties / error / properties / data / properties / reason / description
      Previous value: -"Machine-readable failure mode. Declared by this tool: `invalid_id_format`: An array element is not a single N/W/R-prefixed OSM ID. `rate_limited`: Nominatim returned HTTP 429, or answered HTTP 200 with a throttle document instead of JSON — the one request per second usage policy was exceeded. `upstream_error`: Nominatim returned an unexpected non-2xx status other than 429, or answered HTTP 200 with a body that is not JSON and carries no throttle signature. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `invalid_id_format`: An array element is not a single N/W/R-prefixed OSM ID. `invalid_parameters`: Nominatim returned HTTP 400 — it refused one of the forwarded parameters. Its own message names the parameter and is carried in this error. `rate_limited`: Nominatim returned HTTP 429, or answered HTTP 200 with a throttle document instead of JSON — the one request per second usage policy was exceeded. `upstream_error`: Nominatim returned an unexpected non-2xx status other than 429, or answered HTTP 200 with a body that is not JSON and carries no throttle signature. Other values are possible when a failure originates below the handler."
    • changedOutput schema / properties / error / properties / data / properties / reason / examples
      Previous value: -[
-  "invalid_id_format",
-  "rate_limited",
-  "upstream_error"
-]New value: +[
+  "invalid_id_format",
+  "invalid_parameters",
+  "rate_limited",
+  "upstream_error"
+]
  4. Changed3 schema fields changed
    • addedOutput schema / properties / results / items / properties / boundingbox / items
      Added value: +false
    • addedOutput schema / properties / results / items / properties / boundingbox / maxItems
      Added value: +4
    • addedOutput schema / properties / results / items / properties / boundingbox / minItems
      Added value: +4
  5. Changed8 schema fields changed
    • 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": [
+      "results",
+      "not_found",
+      "total",
+      "attribution"
+    ]
+  },
+  {
+    "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_id_format`: An array element is not a single N/W/R-prefixed OSM ID. `rate_limited`: Nominatim returned HTTP 429, or answered HTTP 200 with a throttle document instead of JSON — the one request per second usage policy was exceeded. `upstream_error`: Nominatim returned an unexpected non-2xx status other than 429, or answered HTTP 200 with a body that is not JSON and carries no throttle signature. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "invalid_id_format",
+            "rate_limited",
+            "upstream_error"
+          ],
+          "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 / properties / results / items / properties / boundingbox / items
      Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "string"
-  },
-  {
-    "type": "string"
-  }
-]
    • addedOutput schema / properties / results / items / properties / boundingbox / prefixItems
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "string"
+  },
+  {
+    "type": "string"
+  }
+]
    • removedOutput schema / required
      Removed value: -[
-  "results",
-  "not_found",
-  "total",
-  "attribution"
-]
  6. Changed3 schema fields changed
    • changedInput schema / properties / extratags / description
      Previous value: -"Include extra OSM tags (phone, website, wikidata, etc.)."New value: +"Include the extra OSM tags each looked-up object carries — contact and metadata tags (phone, website, opening_hours, wikidata) and physical attribute tags alike (surface, tracktype, sac_scale, ele, access). Reports whatever the object happens to carry, so an absent tag describes that object rather than OpenStreetMap."
    • changedOutput schema / properties / results / items / properties / extratags / description
      Previous value: -"Additional OSM tags. Present only when extratags was requested."New value: +"Extra OSM tags this object carries — contact and metadata (phone, website, opening_hours, wikidata) and physical attributes (surface, tracktype, sac_scale, ele, access). Present only when extratags was requested; an absent tag describes this object, not OpenStreetMap."
    • addedOutput schema / properties / tagSelectionCaveat
      Added value: +{
+  "description": "Standing caveat: tag-based selection lives on the Overpass tools (openstreetmap_query_nearby, openstreetmap_query_bbox, openstreetmap_query_raw), never here. extratags decorates the returned objects rather than selecting them, so a missing tag is not evidence the tag is missing from OpenStreetMap. Present when extratags was requested.",
+  "type": "string"
+}
  7. Added

TDQS

A4.5/5.0
Behavior4/5

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

Annotations already establish read-only, idempotent, and open-world behavior. Beyond that, the description discloses that it 'returns only objects named in osm_ids,' lists unresolved IDs 'under not_found,' and cannot select by tag. This adds meaningful behavioral context not present in the 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?

Two dense but purposeful sentences. The first front-loads the core action and resource, and the second packs usage context, output behavior, and alternatives without filler. Every clause earns its place.

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?

For a lookup tool with max 50 IDs, a 100%-covered schema, and an output schema, the description covers the essential context: when to use it, how IDs are prefixed, what it cannot do, and how not_found results are surfaced. Nothing critical is missing.

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

Parameters3/5

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

Schema description coverage is 100%, and each parameter is already well documented in the schema, including the prefix format, array requirement, and extratag contents. The description repeats the N/W/R prefix example but does not add meaning beyond the schema, so the baseline of 3 is appropriate.

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?

The description uses a specific verb and resource: 'Fetch the Nominatim address record for up to 50 known OSM objects by ID.' It clearly distinguishes the tool from discovery siblings by stating it 'cannot select by tag' and by referencing openstreetmap_query_nearby, openstreetmap_query_bbox, and openstreetmap_query_raw.

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?

It explicitly says to use this tool for 'IDs already in hand from openstreetmap_query_nearby or openstreetmap_query_bbox' and directs discovery to 'those tools or openstreetmap_query_raw first.' This gives both when-to-use and when-not-to-use guidance with named alternatives.

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 toolsInspect
Try in Browser
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Resources