Skip to main content
Glama

openstreetmap-mcp-server

by io.github.cyanheads

Look up address details for OSM objects by ID

openstreetmap_lookup_objects
Read-onlyIdempotent

Fetch address details for one or more known OSM objects by their IDs via Nominatim. Each ID must be prefixed with N (node), W (way), or R (relation), e.g., "N240109189", "W50637691", "R146656". Up to 50 IDs per call. Use when an OSM ID is already known from a prior openstreetmap_query_nearby or openstreetmap_query_bbox result — this is more efficient than a geocoding round trip to get the full Nominatim address record. The results are exactly the objects named in osm_ids: extratags decorates them and cannot select them, and there is no way to ask this tool for objects carrying a given tag. Discover such objects with openstreetmap_query_nearby, openstreetmap_query_bbox, or openstreetmap_query_raw, then pass their IDs here.

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 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.

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. Dates show when Glama detected each change.

  1. 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
  2. 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"
-]
  3. 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"
+}
  4. Added

TDQS

A4.9/5.0
Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, the description clarifies that 'extratags decorates them and cannot select them,' so the agent understands that extratags cannot be used as a filter. It further explains open-world semantics: 'an absent tag describes that object rather than OpenStreetMap.' This is meaningful behavioral context beyond what annotations provide.

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 front-loaded with the core purpose, then ID format, then limit, then usage guidance, then limitations. Every sentence contributes either a constraint, an example, or a routing decision. It is information-dense but compact for the scope it covers.

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 an output schema and read-only annotations, the description covers everything needed to invoke it correctly: ID format, array requirement, limit, alternatives, and the extratags limitation. There is no missing guidance that would prevent a correct call.

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 key semantic nuance: extratags 'decorates them and cannot select them,' and results are 'exactly the objects named in osm_ids.' The ID prefix examples and the 50-ID limit reinforce schema info without duplicating it wholesale. This pushes it above baseline, though not maximally because much parameter detail is already in the schema.

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 opens with a specific verb and resource: 'Fetch address details for one or more known OSM objects by their IDs via Nominatim.' It names exact ID formats (N/W/R prefixes) and examples, and it clearly distinguishes itself from the geocoding/search siblings by stating this tool works only from known OSM IDs.

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?

The description explicitly says to use this tool 'when an OSM ID is already known from a prior openstreetmap_query_nearby or openstreetmap_query_bbox result' and positions it as more efficient than a geocoding round trip. It also names the alternatives for discovering objects by tags and explicitly states what this tool cannot do: 'there is no way to ask this tool for objects carrying a given tag.'

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
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.

Resources