A
licenseNot graded
qualityC
maintenanceEnables programmatic queries against the OpenStreetMap database using the Overpass API.
17
MIT
openstreetmap-mcp-server
Server Details
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
If you are the author of this connector, you can claim ownership with GitHub, an HTTP challenge, or a DNS record. Claimed connector authors can inspect health checks, view analytics, and manage their listing.
- Status
- Healthy
- Last Tested
- Transport
- Streamable HTTP
- URL
- Repository
- cyanheads/openstreetmap-mcp-server
- GitHub Stars
- 5
- Server Listing
- @cyanheads/openstreetmap-mcp-server
Available Tools
6 toolsopenstreetmap_lookup_objectsLook up address details for OSM objects by IDARead-onlyIdempotentInspect
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| osm_ids | Yes | 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. | |
| language | No | Preferred language for names (BCP 47 code). | |
| extratags | No | 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. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| total | No | Number of results returned. |
| results | No | Address details for the requested OSM IDs that were found. |
| not_found | No | OSM IDs from the request that returned no result. |
| attribution | No | Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0. |
| tagSelectionCaveat | No | 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. |
TDQS
A4.7/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, open-world, and idempotent hints. The description adds valuable context on extratags behavior (decorates but cannot select) and clarifies that absent tags indicate the object lacks them, reinforcing openWorldHint. This goes beyond annotation coverage.
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?
Every sentence earns its place: purpose, examples, usage conditions, and behavioral clarifications are tightly packed. Front-loaded with the core function and logically organized, with zero fluff.
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 an output schema exists, the description covers purpose, usage, parameter specifics, and behavioral limitations. All necessary context for correct invocation is present, including the 50-ID cap and the discovery-then-lookup workflow, making it complete for this complexity.
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 meaning by explaining the ID prefix format with examples, reinforcing the array requirement, and elaborating on extratags semantics that the schema only labels as 'include extra tags'. This is a clear enhancement beyond 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 clearly states the tool fetches address details for known OSM objects by ID via Nominatim. It explicitly contrasts with geocoding round trips and identifies the sibling tools that discover objects, making its unique role unambiguous.
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?
Provides explicit when-to-use guidance (IDs already known from prior queries) and when-not-to-use (cannot discover objects by tag). Names the alternative discovery tools and explains efficiency advantage, 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.
openstreetmap_query_bboxFind OSM features within a bounding boxARead-onlyIdempotentInspect
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.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| 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
ParametersJSON 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. |
TDQS
A4.6/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations (readOnlyHint, openWorldHint, idempotentHint) already signal safe, deterministic behavior. The description adds valuable operational context: it notes the Overpass backend, that features include full OSM tag sets, clarifies the extratags flag is not applicable (unlike sibling tools), and explains the 10-minute deterministic paging cache. This goes beyond the annotations without contradicting them.
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?
The description is compact for a tool with 11 parameters. It front-loads the primary purpose and then packs each sentence with targeted information (alternatives, parameter selection, paging, extratags). While not minimal, every sentence earns its place, and the structure flows logically from purpose to usage to caveats.
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 the tool's complexity (11 params, output schema present), the description is thorough. It covers the query mode choices, boundary semantics including antimeridian, element type guidance, limit/offset paging determinism, timeout advice, and differentiators from sibling tools. Combined with a full output schema, an agent has everything needed to call this correctly.
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% and each parameter has a detailed description, so the baseline is 3. The description adds semantic value by explicitly stating the 'exactly one of amenity or tag_key/tag_value' constraint (reinforcing the schema's anyOf), explaining that antimeridian crossing is valid, and describing how offset/limit and paging caching work. This aids correct invocation beyond the schema alone.
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 precise verb-resource statement: 'Find OSM features within a rectangular geographic area (bounding box) via the Overpass API.' It immediately distinguishes area surveys from proximity searches and names the sibling tool (openstreetmap_query_nearby) as the alternative, making its scope unmistakable.
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 usage guidance is provided: 'Useful for area surveys where you want everything in a region, not proximity searches' and 'For proximity searches centered on a point, use openstreetmap_query_nearby instead.' It also explains the selection between amenity and tag_key/tag_value, clarifying exclusivity and giving examples. This fully covers when and when not to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstreetmap_query_nearbyFind OSM features near a pointARead-onlyIdempotentInspect
Find OSM features within a radius around a geographic point via the Overpass API. The primary tool for "what's near X?" spatial queries. Use amenity for common POI types (hospital, pharmacy, restaurant, cafe, school, atm, 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. Results include all element types specified (nodes cover standalone POIs, ways cover buildings and areas), each with its full OSM tag set, sorted nearest-first by distance_meters from the center point. The extratags flag is not needed here — it applies only to the Nominatim-backed openstreetmap_search_places, openstreetmap_reverse_geocode, and openstreetmap_lookup_objects tools.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Center latitude in WGS84 decimal degrees. | |
| lon | Yes | Center longitude in WGS84 decimal degrees. | |
| limit | No | Maximum results to return. Applied after the Overpass query — if the area has more features, they are truncated. | |
| offset | No | Number of matching features to skip before applying limit, for paging through a large result set. Features are distance-sorted before paging, so higher offsets return progressively farther matches; the full set is cached ~10 minutes so re-paging costs no extra upstream request. Pass the nextOffset value from a prior truncated response. | |
| amenity | No | OSM amenity tag value (e.g., "hospital", "pharmacy", "restaurant", "school", "atm"). Shortcut for tag_key="amenity". Cannot be combined with tag_key/tag_value. | |
| tag_key | No | OSM tag key for non-amenity queries (e.g., "leisure", "shop", "highway", "natural"). Use with tag_value. Cannot be combined with amenity. | |
| tag_value | No | OSM tag value paired with tag_key (e.g., "park", "supermarket", "primary", "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 like large campuses. Omit the field to search nodes and ways; an empty array is rejected because it can only match nothing. | |
| radius_meters | No | Search radius in meters. Max 50,000m (50km). Keep under 5,000m for dense urban POI queries to avoid slow responses. | |
| timeout_seconds | No | Overpass query timeout in seconds. Increase for large radius or dense areas. |
Output Schema
ParametersJSON 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 larger radius or different 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, up to the limit. |
| truncated | No | True if results were cut at the limit. Reduce radius, 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. |
TDQS
A4.9/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint, openWorldHint, and idempotentHint, but the description adds substantial behavioral context beyond that: result sorting (nearest-first by distance_meters), inclusion of full OSM tag sets, behavior with element types (nodes vs ways), truncation via limit after the Overpass query, paging with offset and distance-sorted order, and a ~10-minute cache for re-paging. It also explicitly notes extratags is not needed here, preventing confusion with sibling tools. These details far exceed 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?
The description is a single, well-structured paragraph that front-loads the core purpose, then covers usage modes, result behavior, and tool differentiation. Each sentence conveys necessary information without redundancy. It ends with a clear note on the extratags flag that prevents misuse. No wasted words, and the structure follows a logical flow from purpose to usage to exclusions.
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?
Despite 10 parameters and an output schema (which isn't shown), the description covers all essential behavioral aspects: how filtering works, exactly one filter requirement, element types, sorting, pagination, cache behavior, and performance guidance for radius. It also clarifies relationships with sibling tools. Nothing an agent needs to correctly invoke this tool is omitted, and the output schema covers return structure.
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?
The input schema covers all 10 parameters with detailed descriptions (100% schema description coverage), so the baseline is 3. The description adds value by providing real-world examples (e.g., 'leisure=park', 'shop=supermarket'), clarifying the choice between amenity and tag_key/tag_value, and explaining element_types semantics (nodes for standalone POIs, ways for buildings). It also warns about radius limits for dense urban areas, which is not in the schema. This enrichment justifies a 4.
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 states a specific verb-resource pair: 'Find OSM features within a radius around a geographic point via the Overpass API.' It explicitly identifies itself as 'The primary tool for "what's near X?" spatial queries,' which distinguishes it from sibling tools like openstreetmap_query_bbox and openstreetmap_search_places. The filtering modes (amenity or tag_key/tag_value) are clearly explained, leaving no ambiguity about what the tool does.
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 gives explicit guidance on when to use this tool vs alternatives: it declares itself the primary spatial point-radius tool and clarifies that the extratags flag applies only to other Nominatim-backed tools. It also tells agents to use amenity for common POIs or tag_key/tag_value for other categories, and states that exactly one of these must be provided. This is explicit when/when-not/alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstreetmap_query_rawExecute a raw Overpass QL queryARead-onlyIdempotentInspect
Execute a raw Overpass QL query for advanced spatial queries that the convenience tools do not cover. Use for multi-type queries, union queries, relation membership, historical queries, or any operation requiring full Overpass QL expressiveness. The query must include [out:json]. Example: "[out:json][timeout:15];node"natural"="peak";out body;" Returns one page of the result set: use limit and offset to page through it, and read totalFound and truncated to see how much the query matched. Validate complex queries at overpass-turbo.eu before use. For simple "what's near X?" or "what's in this area?" queries, use openstreetmap_query_nearby or openstreetmap_query_bbox instead.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum elements to return. Applied after the Overpass query — if the query matched more, they are truncated. | |
| query | Yes | Overpass QL query string. Must include [out:json]. The server sets the endpoint and User-Agent; do not include those. Example: "[out:json][timeout:15];node[\"natural\"=\"peak\"](47.5,-122.5,47.7,-122.2);out body;" | |
| offset | No | Number of matching elements 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; a result over 100000 elements is served but not cached, so paging that far re-queries and depends on the endpoint returning the same order. Pass the nextOffset value from a prior truncated response. | |
| timeout_seconds | No | Query timeout in seconds, bounding how long Overpass itself spends on the query. The [timeout:N] directive in the query string takes precedence if present. The client waits for what is requested here, up to 180s, so a long-running query is not cut off early — but the endpoint enforces its own budget and may answer HTTP 504 first. |
Output Schema
ParametersJSON 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 (check syntax or broaden the filter) from an offset past the end of a non-empty result set (retry at a lower offset). Absent when results were returned. |
| elements | No | Raw Overpass API response elements for this page, up to the limit. Structure varies by query type — nodes have lat/lon, ways have nodes[], relations have members[]. |
| truncated | No | True if elements were cut at the limit. Narrow the query, or page with offset to retrieve the rest. |
| nextOffset | No | Offset to pass on the next call to retrieve the following page of elements. Present only when more elements remain beyond this page. |
| totalFound | No | Total elements returned by Overpass before limit truncation. |
| attribution | No | Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0. |
| data_timestamp | No | OSM data freshness timestamp from the Overpass response. Absent when the endpoint reported no freshness metadata. |
| effectiveQuery | No | The Overpass QL string as sent to the API (after any timeout injection). |
| total_elements | No | Number of elements returned on this page. See totalFound for the full match count. |
| 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. |
TDQS
A4.7/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, openWorld, and idempotent hints, and the description adds valuable behavior beyond them: it explains that only one page is returned, how to page with limit/offset, the meaning of totalFound and truncated, and the caching behavior of the endpoint (including the 100k element limit and re-query caveat). It also notes that the server sets endpoint and User-Agent, which is an operational constraint. No contradiction 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 information-dense but every sentence earns its place: purpose, use cases, required syntax, example, paging behavior, validation tip, and alternatives are all included without redundancy. The opening sentence immediately clarifies the tool's niche and the example is concrete. It is front-loaded and well-organized.
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?
The description is fully complete for a raw query tool: it covers purpose, when to use, syntax requirements, paging mechanics, output signals (totalFound/truncated), validation advice, and alternatives. The output schema exists, so return format details are not required. The caching behavior and timeout precedence are also disclosed, leaving no critical gaps for correct invocation.
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 has a detailed description (limit, offset with caching semantics, timeout with precedence). The tool description reinforces how to use limit/offset for paging but does not add meaning beyond the schema; it mostly echoes the schema's explanations. Baseline 3 is appropriate given complete schema coverage.
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 states a clear verb and resource ('Execute a raw Overpass QL query') and goes further by enumerating specific use cases (multi-type, union, relation membership, historical queries) that distinguish it from the convenience tools. It explicitly names sibling tools for the simple cases, so an agent can differentiate it without inspecting schemas.
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 provides explicit when-to-use guidance (advanced queries requiring full Overpass expressiveness) and when-not-to-use guidance, naming the alternative tools (openstreetmap_query_nearby and openstreetmap_query_bbox) for simple spatial queries. It also advises validating queries at overpass-turbo.eu, covering the practical decision path.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstreetmap_reverse_geocodeReverse geocode coordinates to an addressARead-onlyIdempotentInspect
Convert latitude/longitude coordinates to the nearest address or place name via Nominatim/OpenStreetMap. Returns the closest matching OSM object at the given coordinates. Note: Nominatim finds the nearest indexed OSM object — in dense areas this may differ from the address at the exact coordinate. Use zoom=18 for building-level accuracy, lower zoom values for coarser resolution (e.g., zoom=10 for city-level). The match is made on proximity and layer, never on an OSM attribute tag: extratags decorates the matched object and cannot select one. To find the objects in an area that carry a given tag, use openstreetmap_query_nearby, openstreetmap_query_bbox, or openstreetmap_query_raw.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| lat | Yes | Latitude in WGS84 decimal degrees. | |
| lon | Yes | Longitude in WGS84 decimal degrees. | |
| zoom | No | Address detail level, roughly corresponding to map zoom. 18=building, 16=street, 14=neighbourhood, 12=town, 10=city, 8=county, 5=state, 3=country. | |
| layer | No | Restrict which OSM layer is matched. Comma-separated: address, poi, railway, natural, manmade. Default: address,poi. | |
| language | No | Preferred language for the result (BCP 47 code or Accept-Language string). | |
| extratags | No | Include the extra OSM tags the matched object carries — contact and metadata tags (phone, website, opening_hours, wikidata) and physical attribute tags alike (surface, tracktype, sac_scale, ele, access). Opportunistic, not selective: it reports whatever the matched object happens to carry, so an absent tag describes that object rather than OpenStreetMap, and no value here can steer which object is matched. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| error | No | Present when the call failed. Absent on success. |
| result | No | The closest matching OSM object at the given coordinates. |
| attribution | No | Required data attribution. |
| tagSelectionCaveat | No | 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. |
TDQS
A4.8/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only, open-world, and idempotent behavior, but the description adds critical nuances: the nearest indexed match may differ from the exact coordinate in dense areas, extratags is opportunistic and cannot select the matched object, and matching is by proximity/layer only. These go beyond the annotations and fully disclose the tool's behavior.
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?
The description is compact but dense, with every sentence serving a purpose. It front-loads the core function and then presents caveats and alternatives efficiently. Slightly on the longer side, but nothing is redundant; it remains readable and well-organized.
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?
The tool has an output schema (not shown but noted) and rich annotations. The description covers purpose, limitations (nearest-indexed mismatch), parameter usage guidance, and explicit routing to sibling tools. Nothing critical is missing for an agent to call it correctly and interpret results appropriately.
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% with detailed descriptions, so the baseline is 3. The description adds extra value by explaining the pragmatic implications of zoom (e.g., 'use zoom=18 for building-level accuracy'), clarifying that extratags 'reports whatever the matched object happens to carry' and cannot steer selection, and noting layer is comma-separated with defaults. These nuances are not fully covered 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 clearly states the verb 'Convert' and the resource 'latitude/longitude coordinates to the nearest address or place name', specifying the tool returns the closest matching OSM object. It explicitly distinguishes itself from sibling tools that query by tags or areas, making selection unambiguous.
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?
Provides explicit guidance on zoom levels (zoom=18 for building-level, lower values for coarser resolution) and warns that matching is by proximity and layer, not tag attributes. It names specific alternatives (openstreetmap_query_nearby, openstreetmap_query_bbox, openstreetmap_query_raw) for tag-based queries, telling the agent exactly when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
openstreetmap_search_placesGeocode a place name or addressARead-onlyIdempotentInspect
Convert a place name or address to geographic coordinates and structured place data via Nominatim/OpenStreetMap. Accepts either a free-form query string (e.g., "Space Needle Seattle") or structured address fields (street, city, state, etc.) — the two modes are mutually exclusive. Returns results ordered by Nominatim relevance (importance score). Use countrycodes to restrict results to specific countries. For exhaustive POI lists in an area, use openstreetmap_query_nearby or openstreetmap_query_bbox instead — Nominatim search returns best matches, not all matching objects. Results are matched on name and address relevance, never on an OSM attribute tag: extratags decorates whichever object matched and cannot select one, so a named feature may resolve to a different OSM object than the one carrying the tags you want. To filter or enumerate by tag (surface, sac_scale, ele, access, amenity), use openstreetmap_query_nearby, openstreetmap_query_bbox, or openstreetmap_query_raw.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| city | No | City name (structured query). | |
| layer | No | Filter by data layer. Comma-separated values: address, poi, railway, natural, manmade. Default: no restriction. | |
| limit | No | Maximum results to return. Nominatim may return fewer when additional results do not sufficiently match. Max 40. | |
| query | No | Free-form search string (e.g., "Space Needle Seattle" or "1600 Pennsylvania Ave NW, Washington DC"). Cannot be combined with structured address fields. Keep the query to a POI name plus its city or region. Do not insert a parent institution, campus, or building name between the name and the locality: Nominatim reads commas as an address hierarchy and returns nothing when an intermediate token is not a matching containment level. For example, use "Beinecke Library, New Haven", not "Beinecke Library, Yale University, New Haven". | |
| state | No | State or province (structured query). | |
| county | No | County or district (structured query). | |
| street | No | House number and street name (structured query). Use with city/state/country fields. Cannot be combined with query. | |
| country | No | Country name or ISO 3166-1 alpha-2 code (structured query). | |
| language | No | Preferred language for result names (BCP 47 code or Accept-Language string, e.g., "en", "de", "fr,en"). Defaults to local OSM language. | |
| extratags | No | Include the extra OSM tags the matched object carries — contact and metadata tags (phone, website, opening_hours, wikidata) and physical attribute tags alike (surface, tracktype, sac_scale, ele, access). Opportunistic, not selective: it reports whatever the matched object happens to carry, so an absent tag describes that object rather than OpenStreetMap, and no value here can steer which object is matched. Increases response size. | |
| postalcode | No | Postal or ZIP code (structured query). | |
| featureType | No | Restrict results to a geographic feature type. Automatically implies the address layer. | |
| countrycodes | No | Restrict results to one or more countries. Comma-separated ISO 3166-1 alpha-2 codes (e.g., "us,ca"). Preferred over the structured country field when filtering. | |
| exclude_place_ids | No | OSM refs (N/W/R + id) or Nominatim place_ids to drop from results, forwarded as the exclude_place_ids parameter. Pass the nextExcludeIds value from a prior truncated response to page toward the next-best matches — it emits stable OSM refs when available, which page more reliably than volatile place_ids. When the walk runs out, the call succeeds with zero results and an exhaustion notice rather than failing — treat that as the loop-termination signal. Best-effort progressive retrieval, not a stable cursor — Nominatim ranking can reorder slightly between calls, so already-seen results may shift. |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| cap | No | The limit applied to this request. |
| error | No | Present when the call failed. Absent on success. |
| shown | No | Number of results returned. |
| total | No | Number of results returned. |
| notice | No | Guidance for this page, covering two cases: results were capped at limit (truncated is true — keep paging with nextExcludeIds), or an exclude_place_ids paging walk is exhausted and the page came back empty (the query matched, the walk simply ended, so no rewrite is needed). Tell them apart by truncated and the result count, not by this field being present. Absent when a page returns below the limit without being capped. Carries paging guidance only — the tag-selection caveat has its own field so neither message can overwrite the other. |
| results | No | Geocoding results, ordered by Nominatim relevance (importance score descending). |
| truncated | No | True if the result count equals the requested limit (Nominatim may have more). |
| attribution | No | Required data attribution: Data © OpenStreetMap contributors, ODbL 1.0. |
| effectiveQuery | No | The effective query sent to Nominatim — the free-form query string, or a reconstructed string from the provided structured address fields. |
| nextExcludeIds | No | Accumulated exclude tokens (prior excludes plus this page) to pass as exclude_place_ids on the next call, retrieving the next-best matches. Each token is a stable OSM ref (N/W/R + osm_id) when the result carries one, falling back to the Nominatim place_id otherwise. Present only when results were truncated. Nominatim reports no total, so a truncated page is not proof that more matches exist — the following page may come back exhausted (zero results plus a notice). Best-effort: Nominatim ranking is not perfectly stable across calls. |
| tagSelectionCaveat | No | 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 on every successful response. |
TDQS
A5/5.0
Behavior5/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses numerous behaviors beyond the annotations: results are ordered by Nominatim relevance, extratags is opportunistic and cannot select a different object, exclude_place_ids is a best-effort cursor with potential reordering, and limit may return fewer results. These caveats align with the readOnlyHint/openWorldHint/idempotentHint annotations without contradiction.
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 progressively adds usage modes, alternative routing, and behavioral caveats. While lengthy, every sentence contributes unique value—no redundancy or filler. The structure guides the agent from basic invocation to advanced pitfalls in logical order.
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 tool with 14 parameters and an output schema, the description covers all critical aspects: input modes, country/feature filtering, language handling, the extratags limitation, and the pagination mechanism. It also positions itself against sibling tools, ensuring the agent has everything needed to call it correctly without ambiguity. The output schema handles return details, so its absence in the description is acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 100% schema coverage, the description adds substantial meaning that the schema lacks: detailed guidance on query formatting (comma hierarchy handling), explanation that extratags reflects the matched object's own tags and cannot steer selection, and the paging semantics of exclude_place_ids including stable OSM refs and exhaustion signaling. This goes well beyond the parameter descriptions.
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 clearly states the tool converts a place name or address to geographic coordinates and structured place data via Nominatim/OpenStreetMap. It distinguishes itself from siblings by explicitly noting it returns best matches, not exhaustive lists, and points to alternatives for that purpose. The verb and resource are specific and unambiguous.
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 guidance is provided on when to use this tool versus alternatives: 'For exhaustive POI lists in an area, use openstreetmap_query_nearby or openstreetmap_query_bbox instead' and for tag filtering it lists query_nearby/bbox/raw. It also explains the two mutually exclusive input modes (free-form query vs structured fields) and warns against inserting non-matching hierarchy tokens like 'Beinecke Library, Yale University, New Haven'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Frequently Asked Questions
Claiming proves that you control a remote MCP connector. It does not move, proxy, or interrupt the server.
Open the connector listing, choose Claim ownership, and sign in to Glama.
Complete one verification method:
GitHub identity — fastest for official registry listings. For a namespace such as
io.github.alice/server, link the matching GitHub user or an account that owns the GitHub organization, then choose Claim with GitHub.HTTP challenge — works when you can deploy a public file. Generate a token, publish the exact JSON Glama shows at
/.well-known/glama.jsonon the same origin as the connector, then choose Check HTTP challenge.DNS challenge — works when you control DNS but cannot change the server. Generate a token, create the exact TXT record Glama shows, wait for it to propagate, then choose Check DNS challenge.
After verification, Glama sends a confirmation email and gives you access to listing details, thumbnails, health checks, and analytics. Keep the HTTP file or DNS record in place: Glama periodically checks it and ownership remains verified while the token is discoverable.
The HTTP ownership file has this structure:
{
"$schema": "https://glama.ai/mcp/schemas/connector.json",
"claim": "glama_claim_..."
}Claim tokens are opaque, stable, and bound to the signed-in Glama account. They contain no email address or other personal information. If Glama can no longer discover a verified HTTP or DNS token, it starts a seven-day grace period before removing claim-based access. Restore the same token during that period to keep ownership verified. Never publish an email address, Glama session token, GitHub token, or connector credential as ownership proof.
If verification fails, confirm that you copied the current token exactly. The HTTP file must be public, return valid JSON with a successful HTTP response, and stay on the connector's origin. DNS changes may need more time to propagate. A claim cannot transfer to a different origin or hostname: if the connector target changes, Glama starts the grace period and the new target must be claimed separately after the previous claim is released.
For a connector linked to the official MCP Registry, registry updates continue to replace its name, description, and URL by default. After claiming, open Manage connector and enable Use Glama listing details as the source of truth if edits made on Glama should be preserved. Categories and thumbnails are always managed on Glama; registry linkage and technical connection settings continue to sync.
Control your server's listing on Glama, including description and metadata
Access analytics and receive server usage reports
Get monitoring and health status updates for your server
Feature your server to boost visibility and reach more users
To improve your MCP server's ranking:
Claim ownership of the server listing
Complete the server profile with an accurate description and thumbnail
Provide a test profile so Glama can connect to and evaluate the server
Keep tool definitions clear and complete to earn a high Tool Definition Quality Score (TDQS)
Route real usage through the Glama Gateway; more recorded successful server uses also improve the ranking
For users:
Full audit trail – every tool call is logged with inputs and outputs for compliance and debugging
Granular tool control – enable or disable individual tools per connector to limit what your AI agents can do
Centralized credential management – store and rotate API keys and OAuth tokens in one place
Change alerts – get notified when a connector changes its schema, adds or removes tools, or updates tool definitions, so nothing breaks silently
For server owners:
Proven adoption – public usage metrics on your listing show real-world traction and build trust with prospective users
Tool-level analytics – see which tools are being used most, helping you prioritize development and documentation
Direct user feedback – users can report issues and suggest improvements through the listing, giving you a channel you would not have otherwise
The connector status is unhealthy when Glama is unable to successfully connect to the server. This can happen for several reasons:
The server is experiencing an outage
The URL of the server is wrong
Credentials required to access the server are missing or invalid
If you are the owner of this MCP connector and would like to make modifications to the listing, including providing test credentials for accessing the server, please contact support@glama.ai.
Discussions
No comments yet. Be the first to start the discussion!
Related MCP Connectors
Geocode, reverse geocode, and run Overpass spatial queries on OpenStreetMap data.
OpenCage forward + reverse geocoding (free key, 2500/day)
Geocoding, weather forecasts, and timezone lookups
Nominatim MCP — wraps OpenStreetMap Nominatim geocoding API (free, no auth)
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides forward/reverse geocoding, bounding box extraction, nearby places discovery, batch geocoding, route waypoints, and administrative boundary lookup using OpenStreetMap data.10Apache 2.0
- FlicenseAqualityCmaintenanceEnables querying OpenStreetMap data (buildings, roads, amenities, etc.) via Overpass API and converts them to GeoJSON format for GIS analysis and visualization.86
- AlicenseNot gradedqualityCmaintenanceEnables geocoding and reverse geocoding from OpenStreetMap data using the free Nominatim API.4MIT
Try in Browser
Glama MCP Gateway
Add one secure layer between your agents and this server.
TDQS
A4.7/5.0
Disambiguation5/5
Each tool targets a distinct operation: lookup by ID, bbox query, proximity query, raw Overpass, reverse geocode, and place search. Descriptions explicitly cross-reference when to use each, leaving no ambiguity.
Naming Consistency5/5
All tools follow a consistent openstreetmap_<verb>_<object/qualifier> pattern in snake_case, with clear verb choices (lookup, query, reverse, search) and a coherent query_* subfamily.
Tool Count5/5
Six tools is ideal for a read-only OSM server, covering geocoding, spatial queries, ID lookup, and raw Overpass without redundancy.
Completeness5/5
The surface covers the full lifecycle of geospatial lookups: name-to-coordinates, coordinates-to-address, ID-to-details, area/radius searches, and arbitrary raw queries, with no obvious gaps for the intended domain.