geonames-mcp-server

Look up postal codes in the GeoNames postal database (122 countries): mode code resolves a postal code to its place, admin names, and centroid; mode place_name finds postal codes for a place name; both page with offset, up to 5000; mode nearby lists postal codes within radiusKm (up to 30 km) of a coordinate, nearest first. Ireland returns only Eircode routing keys and Malta only the letter prefix; the United Kingdom (GB), Canada, and the Netherlands hold both full codes and their outward or district prefixes. Check coverage with geonames_list_reference topic postal_countries. Costs 1 GeoNames credit (2 for nearby); a code or place_name lookup with countries that returns nothing at offset 0 also reads the postal coverage list, 1 more credit unless that list is cached. Repeat lookups are cached.

List the direct children of a GeoNames feature — Earth's continents, a continent's countries, a country's first-level divisions, a state's counties, a city's sections — in the administrative tree, or in the tourism tree (islands, coasts, and their municipalities; almost all in Spain) or the dependency tree (a country's dependent territories). Start from a country's geonameId (geonames_get_countries) or any admin division's. Children are mostly admin divisions (class A) and populated places (class P); continents and coasts are class L and islands class T. For other feature types inside a country or admin division, use geonames_search_places with its country in countries and its admin codes (adminLevels of geonames_get_place), which match exactly; a boundingBox also takes in neighboring areas, so keep it for a place that is not a division. GeoNames answers a tourism or dependency request with the administrative children when the feature has no such tree, so the tool compares the two lists and sets sameAsAdministrative when they match, keeping the rows (a real tree can match too). The full child list is fetched once (1 GeoNames credit) and cached, so paging and nameContains filtering are free; a tourism or dependency call also reads the administrative list for the comparison, 1 more credit unless it is cached.

Get GeoNames country facts — ISO alpha-2, alpha-3, and numeric codes, FIPS code, geonameId, capital, population, area in km², continent, languages, currency, postal-code format, and mainland bounding box — for the countries named, a continent, or all 250. The geonameId anchors geonames_get_children (a country's first-level divisions) and geonames_get_hierarchy. The full table is fetched once a day (1 GeoNames credit) and cached.

Return the parent chain of a GeoNames feature, ordered from Earth and its continent through the country and admin divisions down to the feature itself, each with its geonameId, feature code, and coordinates. Use it to find which country, state, and county contain a place, or to fill an admin path for a geonameId. An unknown id returns found: false. Costs 1 GeoNames credit; cached.

Fetch the full GeoNames record for one geonameId: coordinates, feature type, the admin chain with each level's code, name, and geonameId, timezone, bounding box, recorded and DEM elevation, population, Wikipedia URL, names in other languages, postal codes, and external identifiers (IATA, ICAO, UN/LOCODE, Wikidata). Take the geonameId from geonames_search_places, geonames_reverse_geocode, geonames_get_children, or geonames_get_countries. An unknown id returns found: false. Costs 1 GeoNames credit; repeat lookups are cached.

Decode GeoNames vocabulary used by the other tools: topic feature_classes lists the 9 one-letter classes; topic feature_codes lists the 684 feature codes with names and definitions, filterable by class and text; topic postal_countries lists the 122 countries with postal-code data and each one's code range and count. feature_classes and feature_codes are bundled and spend no credits; postal_countries costs 1 GeoNames credit a day (cached).

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.

Search the GeoNames gazetteer of 13M+ places by name and filters: country, admin division by its GeoNames code (adminCode1 TX with countries US for Texas), feature class (P populated places, A admin divisions, T mountains and terrain, H water, S buildings and spots), feature code (PPLC capitals, ADM1 states, MT mountains, AIRP airports), population tier, and bounding box. Results carry the geonameId that geonames_get_place, geonames_get_hierarchy, and geonames_get_children take. The default match requires a query term in the place name while letting other terms match the country or admin names ("Berlin, Germany"). Costs 1 GeoNames credit per call.