Skip to main content
Glama

geonames-mcp-server

by io.github.cyanheads
OverviewDiscussionsAdmin

Reverse geocode with GeoNames

geonames_reverse_geocode
Read-onlyIdempotent

Resolve a latitude/longitude to the country and admin subdivisions that contain it (down to ADM5, each with its geonameId and ISO 3166-2 code where one exists), or the ocean or sea when the point is offshore, plus the nearest populated places with distances; these include neighborhood sections (PPLX) and historical places (PPLH), marked by featureCode. Set featureClasses or featureCodes to list the nearest features of that type instead (peaks, lakes, airports), cities to keep only places above a population tier, and includeTimezone for the IANA timezone with local time, sunrise, and sunset (offshore points get only GeoNames' UTC-offset estimate). A harbor, pier, or shoreline point can fall just outside every country outline and resolve to the sea; coastalBufferKm (up to 50) matches the nearest country within that distance instead. Costs 1 GeoNames credit for containment, with or without the buffer, plus 3 for nearest populated places or 4 for nearest features (nearbyLimit 0 skips them), 1 for the ocean when no country contains the point or lies within the buffer, and 1 for the timezone.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
latYesLatitude in decimal degrees, -90 to 90.
lngYesLongitude in decimal degrees, -180 to 180.
citiesNoKeep only nearby populated places with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. Not combinable with featureClasses or featureCodes.
radiusKmNoRadius in kilometres for the nearby lookup, above 0 and at most 300 (GeoNames' free-tier limit). Default 20.
nearbyLimitNoHow many nearest places or features to list, 0 to 1,000. This tool returns at most 50 per call: a larger nearbyLimit is held to 50, and the notice says so when more lie within the radius. Default 5. 0 skips the nearby lookup and its 3 or 4 credits.
featureCodesNoList the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, AIRP airport), up to 20, as a list. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. Not combinable with cities.
featureClassesNoList the nearest features of these GeoNames classes instead of populated places: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. Not combinable with cities.
coastalBufferKmNoWhen no country contains the point, match the nearest country within this many kilometres, 0 to 50. Default 0: exact containment only. Set it for a harbor, pier, or shoreline point, which can fall just outside a country's outline as GeoNames maps it and otherwise resolves to the sea; a match carries country.distanceInKm. The nearby and timezone lookups keep the exact point. No extra credit.
includeTimezoneNoAlso return the timezone: IANA id, UTC offsets, local time, sunrise, and sunset (1 more credit). Default false.
geonamesUsernameNoYour own GeoNames username, so the call spends that account's free credits instead of the server's. Omit it to use the server's account. The account needs free web services enabled on its geonames.org account page.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe nearbyLimit applied: nearbyLimit as given, or 50 when it asked for more.
latNoThe latitude that was looked up.
lngNoThe longitude that was looked up.
errorNoPresent when the call failed. Absent on success.
oceanNoThe ocean or sea at the point; present only when no country contains it or lies within coastalBufferKm.
shownNoNearby places or features returned.
nearbyNoNearest places or features, nearest first; empty when nearbyKind is none.
noticeNoGuidance when the point is offshore or unmapped, its country was matched within coastalBufferKm, nothing is nearby, more lie within the radius than nearby holds (naming a nearbyLimit held to 50), or no IANA timezone covers it.
countryNoThe country containing the point, or with coastalBufferKm the nearest country within that distance (then distanceInKm is set); absent offshore and in unmapped areas.
timezoneNoThe timezone at the point; present only with includeTimezone.
truncatedNoTrue when more places or features lie within the radius than nearby holds.
nearbyKindNoWhat nearby lists: populated_places, features (featureClasses or featureCodes was set), or none (nearbyLimit 0).
adminLevelsNoAdmin divisions containing the point, first level first; for a country matched within coastalBufferKm, the divisions of its part nearest the point. Empty offshore, and where GeoNames records no subdivision of the country.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed12 schema fields changed
    • changedInput schema / properties / featureClasses / description
      Previous value: -"List the nearest features of these GeoNames classes instead of populated places: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. A list or a comma-separated string; case-insensitive. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. Not combinable with cities."New value: +"List the nearest features of these GeoNames classes instead of populated places: A admin divisions, H water, L areas, P populated places, R roads, S spots and buildings, T terrain, U undersea, V vegetation. With featureCodes too, the two lists intersect: list exactly the classes of those codes, or pass featureCodes alone. Not combinable with cities."
    • changedInput schema / properties / featureCodes / description
      Previous value: -"List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, AIRP airport), up to 20, as a list or a comma-separated string. Case-insensitive; a class prefix (T.MT) is dropped. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. Not combinable with cities."New value: +"List the nearest features with these GeoNames codes instead of populated places (MT mountain, PK peak, LK lake, AIRP airport), up to 20, as a list. Each code implies its class; with featureClasses too, the two lists intersect, so featureClasses must list exactly these codes' classes. geonames_list_reference topic feature_codes lists every code. Not combinable with cities."
    • changedInput schema / properties / nearbyLimit / description
      Previous value: -"How many nearest places or features to list, 0 to 50. Default 5. 0 skips the nearby lookup and its 3 or 4 credits."New value: +"How many nearest places or features to list, 0 to 1,000. This tool returns at most 50 per call: a larger nearbyLimit is held to 50, and the notice says so when more lie within the radius. Default 5. 0 skips the nearby lookup and its 3 or 4 credits."
    • changedInput schema / properties / nearbyLimit / maximum
      Previous value: -50New value: +1000
    • changedOutput schema / properties / adminLevels / items / properties / code / description
      Previous value: -"Admin code at this level."New value: +"GeoNames admin code at this level. At levels 1 to 4, pass it as written to geonames_search_places as that level's adminCode (adminCode1 to adminCode4), with the level 1 code as adminCode1 and country.countryCode in countries, to search inside the division; level 5 has no search filter."
    • changedOutput schema / properties / cap / description
      Previous value: -"The nearbyLimit that was applied."New value: +"The nearbyLimit applied: nearbyLimit as given, or 50 when it asked for more."
    • changedOutput schema / properties / notice / description
      Previous value: -"Guidance when the point is offshore or unmapped, its country was matched within coastalBufferKm, nothing is nearby, nearby is full, or no IANA timezone covers it."New value: +"Guidance when the point is offshore or unmapped, its country was matched within coastalBufferKm, nothing is nearby, more lie within the radius than nearby holds (naming a nearbyLimit held to 50), or no IANA timezone covers it."
    • changedOutput schema / properties / timezone / properties / dstOffsetInHours / description
      Previous value: -"UTC offset in hours on 1 July. Without a timezoneId the offsets are GeoNames' open-water estimate, which has no DST, so this equals rawOffsetInHours."New value: +"UTC offset in hours on 1 July of the current local year. Without a timezoneId the offsets are GeoNames' open-water estimate, which has no DST, so both equal rawOffsetInHours."
    • changedOutput schema / properties / timezone / properties / gmtOffsetInHours / description
      Previous value: -"UTC offset in hours on 1 January."New value: +"UTC offset in hours on 1 January of the current local year."
    • changedOutput schema / properties / timezone / properties / sunrise / description
      Previous value: -"Today's local sunrise, YYYY-MM-DD HH:mm. Absent offshore."New value: +"Local sunrise on localTime's date, YYYY-MM-DD HH:mm. Absent offshore, in polar day or night, and when GeoNames has none for that date."
    • changedOutput schema / properties / timezone / properties / sunset / description
      Previous value: -"Today's local sunset, YYYY-MM-DD HH:mm. Absent offshore."New value: +"Local sunset of the same day as sunrise, YYYY-MM-DD HH:mm; it can fall after midnight. Absent offshore, in polar day or night, and when GeoNames has none for that date."
    • changedOutput schema / properties / truncated / description
      Previous value: -"True when nearby is full at nearbyLimit, so more may lie within the radius."New value: +"True when more places or features lie within the radius than nearby holds."
  2. First observed

TDQS

A4.7/5.0
Behavior5/5

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

Annotations only cover readOnly/openWorld/idempotent; the description goes well beyond them, disclosing exact credit costs per component, the 50-result cap on nearbyLimit, the sea fallback for offshore points, UTC-offset-only timezone for offshore, and the PPLX/PPLH featureCode marking of results.

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?

Front-loaded with the primary resolution behavior, and every sentence carries information. The trailing credit-cost sentence is dense and run-on, which costs readability but not correctness.

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?

With an output schema present, return values need no explanation; the description fully covers the behaviors an agent needs to call correctly — cost model, offshore/coastal edge cases, parameter interactions, and per-account credit usage via geonamesUsername.

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?

Schema coverage is 100%, so the baseline is 3, but the description adds cross-parameter semantics the schema does not: cities is non-combinable with featureClasses/featureCodes, featureCodes and featureClasses intersect, and each optional branch carries a specific credit cost. That is real value beyond the schema text.

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 ('Resolve a latitude/longitude to the country and admin subdivisions ... or the ocean or sea'), and enumerates the secondary outputs (nearest populated places, features, timezone). An agent can distinguish this from geonames_search_places or geonames_get_place purely from the description.

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

Usage Guidelines4/5

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

Gives explicit conditions for the option branches: set featureClasses/featureCodes to list other feature types, cities to filter by population tier, coastalBufferKm when a harbor/pier/shoreline point falls outside a country outline, and nearbyLimit 0 to skip the nearby lookup. It does not route between named sibling tools, which keeps it short of a 5.

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

All geonames-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