Skip to main content
Glama
Sign In

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 known OSM objects by ID, 50 per call with any more returned under deferred_ids, 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 and lists those with no Nominatim record under not_found (Nominatim skips unnamed and non-place objects, so such an ID may still exist). It cannot select by tag, so discover objects with those tools or openstreetmap_query_raw first.

Input 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 500 entries; duplicates are dropped and the first 50 unique IDs are looked up per call, the rest returned under deferred_ids to pass on the next 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

NameRequiredDescriptionDefault
errorNoPresent when the call failed. Absent on success.
totalNoNumber of results returned.
noticeNoPresent when IDs were deferred or not_found is non-empty: the deferral first, then what not_found means and the openstreetmap_query_raw query and limit that return whichever of those IDs exist. Absent otherwise.
resultsNoAddress details for the requested OSM IDs that were found.
not_foundNoOSM IDs from the request with no Nominatim record, each listed once in canonical form (prefix uppercased, leading zeros dropped). The object does not exist, or it exists and Nominatim does not index it (unnamed or non-place features such as street lamps or building parts); notice gives the openstreetmap_query_raw query that tells the two apart.
attributionNoRequired data attribution: Data © OpenStreetMap contributors, ODbL 1.0.
deferred_idsNoUnique IDs past the first 50, not looked up on this call; pass them as osm_ids on the next call. Absent when every ID was looked up.
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. Changed1 schema field 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. `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."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 400 or 429, or HTTP 200 with a non-JSON body carrying no throttle signature, or never answered: connection refused, host not found, or timed out. Other values are possible when a failure originates below the handler."
  2. Changed5 schema fields changed
    • changedInput schema / properties / osm_ids / description
      Previous value: -"OSM 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."New value: +"OSM 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 500 entries; duplicates are dropped and the first 50 unique IDs are looked up per call, the rest returned under deferred_ids to pass on the next call."
    • changedInput schema / properties / osm_ids / maxItems
      Previous value: -50New value: +500
    • addedOutput schema / properties / deferred_ids
      Added value: +{
+  "description": "Unique IDs past the first 50, not looked up on this call; pass them as osm_ids on the next call. Absent when every ID was looked up.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
    • changedOutput schema / properties / not_found / description
      Previous value: -"OSM IDs from the request that returned no result."New value: +"OSM IDs from the request with no Nominatim record, each listed once in canonical form (prefix uppercased, leading zeros dropped). The object does not exist, or it exists and Nominatim does not index it (unnamed or non-place features such as street lamps or building parts); notice gives the openstreetmap_query_raw query that tells the two apart."
    • addedOutput schema / properties / notice
      Added value: +{
+  "description": "Present when IDs were deferred or not_found is non-empty: the deferral first, then what not_found means and the openstreetmap_query_raw query and limit that return whichever of those IDs exist. Absent otherwise.",
+  "type": "string"
+}
  3. 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."
  4. 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."
  5. 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"
+]
  6. 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
  7. 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"
-]
  8. 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"
+}
  9. Added

TDQS

A4.6/5.0
Behavior5/5

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

Annotations already cover the read-only, open-world, idempotent profile, and the description goes well beyond them: 50 per call with overflow in deferred_ids, IDs with no record landing in not_found, and the important caveat that Nominatim skips unnamed/non-place objects so absence of a record does not mean the object does not exist. That is real behavioral context an agent would otherwise get wrong.

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?

Three sentences, front-loaded with the verb and resource, then batching, then the sibling routing. Dense but purposeful; the nested parentheticals make the middle sentence slightly harder to scan than it needs to be.

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?

An output schema exists, so return shapes need not be spelled out, yet the description still flags the three result buckets (records, deferred_ids, not_found) that matter for driving the next call. For a 3-parameter lookup tool with two siblings to disambiguate from, nothing material 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 coverage is 100% and the schema itself documents the N/W/R prefix convention, the 500 cap, duplicate dropping, and the 50-per-call batching. The description restates the same batching and prefix rules rather than adding meaning, so the baseline 3 applies; it adds nothing about language or extratags semantics.

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 ("Fetch the Nominatim address record for known OSM objects by ID") and immediately names the ID format (N/W/R prefixes). It also distinguishes itself from the query siblings by declaring it "cannot select by tag", so an agent can route correctly without opening the schema.

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?

Explicit routing: "Use it for IDs already in hand from openstreetmap_query_nearby or openstreetmap_query_bbox" and "discover objects with those tools or openstreetmap_query_raw first." Both the when-to-use and the when-not-to-use alternatives are named.

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