geonames-mcp-server
An MCP server that provides access to the GeoNames gazetteer, allowing agents to search for places, retrieve full records, traverse administrative hierarchies, perform reverse geocoding, find postal codes, and access country facts.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://geonames.caseyjhand.com/mcpWhat its tools do
8 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Search places by name, country, or administrative division
- Reverse geocode coordinates to find country and admin subdivisions
- Look up postal codes by place name or coordinate
- Retrieve country facts including ISO codes and currency
Source and maintenance
Community listingRegistry 0.2.0
- Maintenance checked
Protocol and capabilities
- Server
- geonames-mcp-server 0.2.0
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 8 advertised
- Resources
- 1 advertised
- Resource templates
- 1 advertised
- Prompts
- 0 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
8 advertised
geonames_search_places — Search GeoNames places
Advertised read-onlyOpen-world
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.
geonames_search_places input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"limit": {
"type": "integer",
"default": 10,
"maximum": 1000,
"minimum": 1,
"description": "Maximum entries to return, 1 to 1,000. This tool returns at most 100 per call: a larger limit is held to 100, and the notice says so when more entries remain. Default 10."
},
"match": {
"enum": [
"name_required",
"any_field",
"exact_name",
"name_prefix"
],
"type": "string",
"description": "How query is matched. name_required (the default) needs at least one query term in the place name while other terms may match the country or admin names; any_field lets every term match any of those fields; exact_name matches the whole name exactly, alternate and historical names included; name_prefix matches names that start with query. Needs query."
},
"query": {
"type": "string",
"maxLength": 200,
"description": "Place name to search for, such as Springfield or \"Berlin, Germany\", up to 200 characters. match sets how it is compared. Omit it to search by filters alone, which then needs at least one of countries, featureClasses, featureCodes, or boundingBox (cities alone is not enough)."
},
"cities": {
"enum": [
"cities1000",
"cities5000",
"cities15000"
],
"type": "string",
"description": "Keep only populated places (class P) with a population of at least 1,000 (cities1000), 5,000 (cities5000), or 15,000 (cities15000), plus seats of admin divisions: GeoNames' cities tiers. A city's sections (PPLX) with their own population pass too. Beside featureClasses or featureCodes, list only class P or class-P codes such as PPLC."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 5000,
"minimum": 0,
"description": "Entries to skip before the first one returned, for paging, 0 to 5000. Default 0."
},
"orderBy": {
"enum": [
"relevance",
"population"
],
"type": "string",
"description": "Result order: relevance or population, largest first. Omit it for GeoNames' own order, which matches relevance except with match name_prefix."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^([A-Z]{2,3}|\\d{3})$",
"description": "ISO 3166-1 alpha-2, alpha-3, or three-digit numeric country code."
},
"maxItems": 10,
"description": "ISO 3166-1 country codes, up to 10, as a list: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. UK is accepted for GB and FL for LI. A listed country also returns the territories GeoNames files under it (GB also returns IM, JE, and GG), each result naming its own country in countryCode."
},
"adminCode1": {
"type": "string",
"pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
"description": "First-level admin division (state, province, region) to search inside, by its GeoNames admin code: TX is Texas in US. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 1), or from adminCode1 on rows of geonames_search_places, geonames_get_hierarchy, and geonames_get_children. GeoNames codes are neither ISO 3166-2 nor postal admin codes: Bavaria is 02, not BY. Needs exactly one country in countries. 1 to 20 letters or digits, zero padding kept (02, not 2). Case-insensitive."
},
"adminCode2": {
"type": "string",
"pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
"description": "Second-level admin division (a US county, a French département) to search inside, by its GeoNames admin code: 033 is King County in WA. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 2). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept (033, not 33). Case-insensitive."
},
"adminCode3": {
"type": "string",
"pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
"description": "Third-level admin division to search inside, by its GeoNames admin code: 09162 is Munich in DE. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 3). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept. Case-insensitive."
},
"adminCode4": {
"type": "string",
"pattern": "^\\s*[A-Za-z0-9]{1,20}\\s*$",
"description": "Fourth-level admin division to search inside, by its GeoNames admin code: 92012 is Boulogne-Billancourt in FR. Take it from geonames_get_place or geonames_reverse_geocode (adminLevels[].code at level 4). Needs adminCode1 and exactly one country in countries. 1 to 20 letters or digits, zero padding kept. Case-insensitive."
},
"boundingBox": {
"type": "object",
"required": [
"north",
"south",
"east",
"west"
],
"properties": {
"east": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Eastern longitude bound, decimal degrees, -180 to 180."
},
"west": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Western longitude bound, decimal degrees, -180 to 180; below east."
},
"north": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Northern latitude bound, decimal degrees, -90 to 90."
},
"south": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Southern latitude bound, decimal degrees, -90 to 90; below north."
}
},
"description": "Keep only places inside this box. The box cannot cross the 180° meridian: split such an area into two searches.",
"additionalProperties": false
},
"featureCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z0-9]{2,5}$",
"description": "GeoNames feature code without its class prefix."
},
"maxItems": 20,
"description": "GeoNames feature codes (PPLC capital, ADM1 state, MT mountain, 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."
},
"featureClasses": {
"type": "array",
"items": {
"enum": [
"A",
"H",
"L",
"P",
"R",
"S",
"T",
"U",
"V"
],
"type": "string",
"description": "One-letter GeoNames feature class."
},
"maxItems": 9,
"description": "GeoNames feature classes: 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."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Your 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."
}
},
"additionalProperties": false
}geonames_search_places output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"places",
"totalCount",
"effectiveQuery",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit applied: limit as given, or 100 when it asked for more."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"query_or_filter_required",
"query_required",
"unknown_country_code",
"unknown_feature_code",
"admin_code_unscoped",
"feature_filter_mismatch",
"invalid_bounding_box",
"username_required",
"caller_account_rejected",
"server_account_rejected",
"quota_exhausted",
"upstream_rejected_parameter"
],
"description": "Machine-readable failure mode. Declared by this tool: `query_or_filter_required`: Neither query nor a narrowing filter (countries, featureClasses, featureCodes, boundingBox) was given. `query_required`: match was set without query. `unknown_country_code`: A countries entry, once mapped to alpha-2, is none of the 250 country codes or the retired AN, CS, and YU: an alpha-2 such as EL or EU, or an unassigned alpha-3 or numeric code. `unknown_feature_code`: A featureCodes entry is not a GeoNames feature code. `admin_code_unscoped`: An admin code is set without exactly one country in countries, or adminCode2 to adminCode4 without adminCode1: codes repeat across countries, and lower-level codes across first-level divisions. `feature_filter_mismatch`: featureClasses and featureCodes are both set and a code's class is not listed or a listed class has no listed code, or cities (class P only) is set beside another class or a code outside class P. GeoNames intersects the filters, so those entries match nothing. `invalid_bounding_box`: boundingBox has south greater than or equal to north, or west greater than or equal to east. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Places returned on this page."
},
"notice": {
"type": "string",
"description": "Guidance: why nothing matched, or how to reach the next page (naming a limit held to 100), and which places on the page lie in countries that countries does not list."
},
"places": {
"type": "array",
"items": {
"type": "object",
"required": [
"geonameId",
"name",
"toponymName"
],
"properties": {
"lat": {
"type": "number",
"description": "Latitude in decimal degrees. Absent when GeoNames sent none."
},
"lng": {
"type": "number",
"description": "Longitude in decimal degrees. Absent when GeoNames sent none."
},
"name": {
"type": "string",
"description": "Name of the place, as GeoNames displays it."
},
"geonameId": {
"type": "number",
"description": "GeoNames feature id: pass it to geonames_get_place, geonames_get_hierarchy, or geonames_get_children."
},
"iso3166_2": {
"type": "string",
"description": "ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO."
},
"adminCode1": {
"type": "string",
"description": "Code of the first-order admin division (state, province) containing it."
},
"adminName1": {
"type": "string",
"description": "Name of the first-order admin division containing it."
},
"population": {
"type": "number",
"description": "Population. Absent when GeoNames records none."
},
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 code of the containing country."
},
"countryName": {
"type": "string",
"description": "Name of the containing country."
},
"featureCode": {
"type": "string",
"description": "Feature code, such as PPLC (capital) or ADM1 (first-order division)."
},
"featureName": {
"type": "string",
"description": "GeoNames' name for the feature code."
},
"toponymName": {
"type": "string",
"description": "GeoNames' main name for the feature, often the local-language form."
},
"featureClass": {
"type": "string",
"description": "One-letter feature class (P populated place, A admin division, …)."
},
"featureClassName": {
"type": "string",
"description": "GeoNames' label for the class."
}
},
"description": "One matching place.",
"additionalProperties": false
},
"description": "Places on this page, in the requested order."
},
"truncated": {
"type": "boolean",
"description": "True when more matching places remain past this page."
},
"nextOffset": {
"type": "number",
"description": "Offset of the next page; absent on the last page and once offset is 5000. Capped at 5000, the last offset GeoNames' free service accepts, so that page can repeat rows of this one."
},
"totalCount": {
"type": "number",
"description": "GeoNames' count of matching places, before paging."
},
"effectiveQuery": {
"type": "string",
"description": "The match mode, query, and filters as the server sent them to GeoNames."
}
},
"additionalProperties": false
}geonames_search_places annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}geonames_get_place — Get a GeoNames place
Advertised read-onlyOpen-world
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.
geonames_get_place input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geonameId"
],
"properties": {
"geonameId": {
"type": "string",
"pattern": "^[1-9]\\d*$",
"description": "GeoNames feature id as a digit string up to 2147483647, such as \"5809844\" (Seattle): the geonameId the other geonames tools return, sent as a string."
},
"nameLanguages": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[a-z]{2,3}(-[a-z0-9]{2,8})*$",
"description": "Language tag or prefix, such as en, de, or zh-tw."
},
"maxItems": 20,
"description": "Keep only alternate names in these languages, up to 20, as a list. A tag also matches its regional forms: zh keeps names GeoNames tags zh, zh-CN, or zh-TW. Omit to return every alternate name, including those under GeoNames pseudo-language tags (abbr, phon, piny, fr_1793), which this filter cannot select. Postal codes, links, and identifiers are unaffected."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Your 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."
}
},
"additionalProperties": false
}geonames_get_place output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"found"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"username_required",
"caller_account_rejected",
"server_account_rejected",
"quota_exhausted",
"upstream_rejected_parameter"
],
"description": "Machine-readable failure mode. Declared by this tool: `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"found": {
"type": "boolean",
"description": "False when GeoNames has no feature with this geonameId."
},
"place": {
"type": "object",
"required": [
"geonameId",
"name",
"toponymName",
"adminLevels",
"alternateNames",
"postalCodes",
"links",
"identifiers"
],
"properties": {
"lat": {
"type": "number",
"description": "Latitude in decimal degrees. Absent when GeoNames sent none."
},
"lng": {
"type": "number",
"description": "Longitude in decimal degrees. Absent when GeoNames sent none."
},
"name": {
"type": "string",
"description": "Name of the place, as GeoNames displays it."
},
"links": {
"type": "array",
"items": {
"type": "string",
"description": "A URL."
},
"description": "Web pages GeoNames links to the place, as received."
},
"timezone": {
"type": "object",
"properties": {
"timezoneId": {
"type": "string",
"description": "IANA timezone id, such as Europe/Paris."
},
"dstOffsetInHours": {
"type": "number",
"description": "UTC offset in hours on 1 July of the current year in this zone."
},
"gmtOffsetInHours": {
"type": "number",
"description": "UTC offset in hours on 1 January of the current year in this zone."
}
},
"description": "The timezone GeoNames associates with this record, not one looked up at its coordinates: on a feature with no country (an ocean, a sea, a continent) it can differ from the time there. For the time at a point, call geonames_reverse_geocode with includeTimezone. Absent when GeoNames sends none.",
"additionalProperties": false
},
"asciiName": {
"type": "string",
"description": "The name in plain ASCII characters."
},
"geonameId": {
"type": "number",
"description": "GeoNames feature id."
},
"iso3166_2": {
"type": "string",
"description": "ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO."
},
"population": {
"type": "number",
"description": "Population. Absent when GeoNames records none."
},
"adminLevels": {
"type": "array",
"items": {
"type": "object",
"required": [
"level"
],
"properties": {
"code": {
"type": "string",
"description": "The division's GeoNames admin code. 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 countryCode in countries, to search inside the division; level 5 has no search filter."
},
"name": {
"type": "string",
"description": "The division's name."
},
"level": {
"type": "number",
"description": "Admin level, 1 (state, province) through 5."
},
"geonameId": {
"type": "number",
"description": "The division's geonameId, where GeoNames gives one."
}
},
"description": "One admin division containing the place.",
"additionalProperties": false
},
"description": "Admin divisions containing the place, first level first."
},
"boundingBox": {
"type": "object",
"required": [
"north",
"south",
"east",
"west"
],
"properties": {
"east": {
"type": "number",
"description": "Eastern longitude bound, decimal degrees."
},
"west": {
"type": "number",
"description": "Western longitude bound, decimal degrees."
},
"north": {
"type": "number",
"description": "Northern latitude bound, decimal degrees."
},
"south": {
"type": "number",
"description": "Southern latitude bound, decimal degrees."
}
},
"description": "Bounding box of the feature. Absent for most points.",
"additionalProperties": false
},
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 code of the containing country."
},
"countryName": {
"type": "string",
"description": "Name of the containing country."
},
"featureCode": {
"type": "string",
"description": "Feature code, such as PPLC (capital) or ADM1 (first-order division)."
},
"featureName": {
"type": "string",
"description": "GeoNames' name for the feature code."
},
"identifiers": {
"type": "array",
"items": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"enum": [
"iata",
"icao",
"faac",
"tcid",
"unlc",
"wkdt"
],
"type": "string",
"description": "Identifier scheme: iata airport, icao airport, faac FAA airport, tcid Transport Canada airport, unlc UN/LOCODE, wkdt Wikidata."
},
"value": {
"type": "string",
"description": "The identifier."
}
},
"description": "One external identifier.",
"additionalProperties": false
},
"description": "External identifiers of the place."
},
"postalCodes": {
"type": "array",
"items": {
"type": "string",
"description": "A postal code."
},
"description": "Postal codes GeoNames links to this feature. The list can be shorter than what geonames_find_postal_codes returns for the place, so it is not the complete set."
},
"toponymName": {
"type": "string",
"description": "GeoNames' main name for the feature, often the local-language form."
},
"featureClass": {
"type": "string",
"description": "One-letter feature class (P populated place, A admin division, …)."
},
"wikipediaUrl": {
"type": "string",
"description": "English Wikipedia article, as GeoNames sends it (without a scheme)."
},
"continentCode": {
"type": "string",
"description": "Continent code: AF, AN, AS, EU, NA, OC, or SA."
},
"alternateNames": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"lang": {
"type": "string",
"description": "ISO 639 language tag, or a GeoNames pseudo-language: abbr abbreviation, phon phonetic, piny pinyin, fr_1793 French Revolution name. Absent when untagged."
},
"name": {
"type": "string",
"description": "The alternate name."
},
"isShortName": {
"type": "boolean",
"description": "True when GeoNames marks this a short name."
},
"isPreferredName": {
"type": "boolean",
"description": "True when GeoNames marks this the preferred name in its language."
}
},
"description": "One alternate name.",
"additionalProperties": false
},
"description": "Names in other languages and forms, filtered by nameLanguages when given."
},
"countryGeonameId": {
"type": "number",
"description": "The containing country's geonameId, for geonames_get_children or geonames_get_place."
},
"featureClassName": {
"type": "string",
"description": "GeoNames' label for the class."
},
"elevationInMeters": {
"type": "number",
"description": "Recorded elevation in metres. Often absent."
},
"demElevationInMeters": {
"type": "number",
"description": "Elevation from the SRTM3 digital elevation model, in metres."
}
},
"description": "The full record; absent when found is false.",
"additionalProperties": false
},
"notice": {
"type": "string",
"description": "Present when the record has no country but carries a timezone: says the zone is the one GeoNames associates with the record, and how to get the time at a point."
},
"guidance": {
"type": "string",
"description": "What to do next; present only when found is false."
}
},
"additionalProperties": false
}geonames_get_place annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}geonames_get_hierarchy — Get a GeoNames hierarchy
Advertised read-onlyOpen-world
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.
geonames_get_hierarchy input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geonameId"
],
"properties": {
"geonameId": {
"type": "string",
"pattern": "^[1-9]\\d*$",
"description": "GeoNames feature id as a digit string up to 2147483647, such as \"5809844\" (Seattle): the geonameId the other geonames tools return, sent as a string."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Your 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."
}
},
"additionalProperties": false
}geonames_get_hierarchy output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"found",
"geonameId",
"chain"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"chain": {
"type": "array",
"items": {
"type": "object",
"required": [
"geonameId",
"name",
"toponymName"
],
"properties": {
"lat": {
"type": "number",
"description": "Latitude in decimal degrees. Absent when GeoNames sent none."
},
"lng": {
"type": "number",
"description": "Longitude in decimal degrees. Absent when GeoNames sent none."
},
"name": {
"type": "string",
"description": "Name of this level, as GeoNames displays it."
},
"geonameId": {
"type": "number",
"description": "GeoNames feature id of this level."
},
"iso3166_2": {
"type": "string",
"description": "ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO."
},
"adminCode1": {
"type": "string",
"description": "First-order admin division code. Absent above that level."
},
"population": {
"type": "number",
"description": "Population. Absent when GeoNames records none."
},
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code. Absent on Earth and continent rows."
},
"featureCode": {
"type": "string",
"description": "Feature code: AREA (Earth), CONT, PCLI (country), ADM1–ADM5, PPL, …"
},
"featureName": {
"type": "string",
"description": "GeoNames' name for the feature code."
},
"toponymName": {
"type": "string",
"description": "GeoNames' main name for the feature, often the local-language form."
},
"featureClass": {
"type": "string",
"description": "One-letter feature class (L area, A admin division, P populated place, …)."
}
},
"description": "One level of the chain.",
"additionalProperties": false
},
"description": "Administrative ancestors, Earth first and the requested feature last; empty when found is false. Levels a feature does not sit under are skipped."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"username_required",
"caller_account_rejected",
"server_account_rejected",
"quota_exhausted",
"upstream_rejected_parameter"
],
"description": "Machine-readable failure mode. Declared by this tool: `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"found": {
"type": "boolean",
"description": "False when GeoNames has no feature with this geonameId."
},
"guidance": {
"type": "string",
"description": "What to do next; present only when found is false."
},
"geonameId": {
"type": "number",
"description": "The geonameId that was requested."
}
},
"additionalProperties": false
}geonames_get_hierarchy annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}geonames_get_children — List GeoNames children
Advertised read-onlyOpen-world
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.
geonames_get_children input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geonameId"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 1,
"description": "Maximum entries to return, 1 to 1,000. This tool returns at most 500 per call: a larger limit is held to 500, and the notice says so when more entries remain. Default 100."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries to skip before the first one returned, for paging. Default 0."
},
"geonameId": {
"type": "string",
"pattern": "^[1-9]\\d*$",
"description": "GeoNames id of the parent feature as a digit string up to 2147483647, such as \"6252001\" (United States): the geonameId the other geonames tools return, sent as a string."
},
"hierarchy": {
"enum": [
"administrative",
"tourism",
"dependency"
],
"type": "string",
"default": "administrative",
"description": "Which tree to descend: administrative (the default: continents (class L), countries, admin divisions, populated places), tourism (islands (class T), coasts (class L), and their municipalities; almost all in Spain), or dependency (a country's dependent territories). For a feature with no tourism or dependency tree, GeoNames answers with its administrative children, which sameAsAdministrative flags; the comparison reads the administrative list, 1 more credit unless it is cached."
},
"nameContains": {
"type": "string",
"maxLength": 100,
"description": "Keep only children whose name or toponym name contains every word of this text as a substring (kansas also matches Arkansas), ignoring case, accents, and punctuation. Give at least one letter or digit."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Your 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."
}
},
"additionalProperties": false
}geonames_get_children output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"found",
"parentGeonameId",
"hierarchy",
"children",
"totalCount",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit applied: limit as given, or 500 when it asked for more."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"name_contains_unsearchable",
"username_required",
"caller_account_rejected",
"server_account_rejected",
"quota_exhausted",
"upstream_rejected_parameter"
],
"description": "Machine-readable failure mode. Declared by this tool: `name_contains_unsearchable`: nameContains is not blank but holds no letter or digit (only punctuation, symbols, emoji, or invisible characters), so it would match every child. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"found": {
"type": "boolean",
"description": "False when GeoNames has no feature with this geonameId."
},
"shown": {
"type": "number",
"description": "Children returned on this page."
},
"notice": {
"type": "string",
"description": "Guidance when a tourism or dependency answer is the administrative children, there are no children, nothing matched, the offset is past the end, more pages remain (naming a limit held to 500), or GeoNames holds more children than it returns."
},
"children": {
"type": "array",
"items": {
"type": "object",
"required": [
"geonameId",
"name",
"toponymName"
],
"properties": {
"lat": {
"type": "number",
"description": "Latitude in decimal degrees. Absent when GeoNames sent none."
},
"lng": {
"type": "number",
"description": "Longitude in decimal degrees. Absent when GeoNames sent none."
},
"name": {
"type": "string",
"description": "Name of the child, as GeoNames displays it."
},
"geonameId": {
"type": "number",
"description": "GeoNames feature id of the child: pass it to geonames_get_children again to descend further, or to geonames_get_place."
},
"iso3166_2": {
"type": "string",
"description": "ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO."
},
"adminCode1": {
"type": "string",
"description": "Code of the first-order admin division containing it."
},
"adminName1": {
"type": "string",
"description": "Name of the first-order admin division containing it."
},
"population": {
"type": "number",
"description": "Population. Absent when GeoNames records none."
},
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 code of the containing country."
},
"featureCode": {
"type": "string",
"description": "Feature code, such as ADM1 (first-order division) or PPLX (section)."
},
"featureName": {
"type": "string",
"description": "GeoNames' name for the feature code."
},
"toponymName": {
"type": "string",
"description": "GeoNames' main name for the feature, often the local-language form."
},
"featureClass": {
"type": "string",
"description": "One-letter feature class (A admin division, P populated place, …)."
}
},
"description": "One child feature.",
"additionalProperties": false
},
"description": "Children on this page, in GeoNames' order; empty when found is false or the feature has none."
},
"guidance": {
"type": "string",
"description": "What to do next; present only when found is false."
},
"hierarchy": {
"enum": [
"administrative",
"tourism",
"dependency"
],
"type": "string",
"description": "The tree that was descended."
},
"truncated": {
"type": "boolean",
"description": "True when more children remain past this page."
},
"nextOffset": {
"type": "number",
"description": "Offset of the next page; absent on the last page."
},
"totalCount": {
"type": "number",
"description": "Children matching nameContains, before paging."
},
"parentGeonameId": {
"type": "number",
"description": "The geonameId whose children were requested."
},
"sameAsAdministrative": {
"type": "boolean",
"description": "Tourism and dependency trees only, when the feature has children there: true when they are exactly its administrative children (same geonameIds and total). GeoNames answers with the administrative children when a feature has no such tree, so true most likely means it has none; a real tree can also match."
}
},
"additionalProperties": false
}geonames_get_children annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}geonames_reverse_geocode — Reverse geocode with GeoNames
Advertised read-onlyOpen-world
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.
geonames_reverse_geocode input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"lat",
"lng"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude in decimal degrees, -90 to 90."
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude in decimal degrees, -180 to 180."
},
"cities": {
"enum": [
"cities1000",
"cities5000",
"cities15000"
],
"type": "string",
"description": "Keep 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. A city's sections (PPLX) with their own population pass too. Not combinable with featureClasses or featureCodes."
},
"radiusKm": {
"type": "number",
"default": 20,
"maximum": 300,
"description": "Radius in kilometres for the nearby lookup, above 0 and at most 300 (GeoNames' free-tier limit). Default 20.",
"exclusiveMinimum": 0
},
"nearbyLimit": {
"type": "integer",
"default": 5,
"maximum": 1000,
"minimum": 0,
"description": "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."
},
"featureCodes": {
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z0-9]{2,5}$",
"description": "GeoNames feature code without its class prefix."
},
"maxItems": 20,
"description": "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."
},
"featureClasses": {
"type": "array",
"items": {
"enum": [
"A",
"H",
"L",
"P",
"R",
"S",
"T",
"U",
"V"
],
"type": "string",
"description": "One-letter GeoNames feature class."
},
"maxItems": 9,
"description": "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."
},
"coastalBufferKm": {
"type": "number",
"default": 0,
"maximum": 50,
"minimum": 0,
"description": "When 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."
},
"includeTimezone": {
"type": "boolean",
"default": false,
"description": "Also return the timezone: IANA id, UTC offsets, local time, sunrise, and sunset (1 more credit). Default false."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Your 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."
}
},
"additionalProperties": false
}geonames_reverse_geocode output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"lat",
"lng",
"adminLevels",
"nearbyKind",
"nearby",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The nearbyLimit applied: nearbyLimit as given, or 50 when it asked for more."
},
"lat": {
"type": "number",
"description": "The latitude that was looked up."
},
"lng": {
"type": "number",
"description": "The longitude that was looked up."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"unknown_feature_code",
"conflicting_filters",
"feature_filter_mismatch",
"username_required",
"caller_account_rejected",
"server_account_rejected",
"quota_exhausted",
"upstream_rejected_parameter"
],
"description": "Machine-readable failure mode. Declared by this tool: `unknown_feature_code`: A featureCodes entry is not a GeoNames feature code. `conflicting_filters`: cities was combined with featureClasses or featureCodes. `feature_filter_mismatch`: featureClasses and featureCodes are both set and a code's class is not listed or a listed class has no listed code. GeoNames intersects the two lists, so those entries match nothing. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"ocean": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Name of the ocean or sea."
},
"geonameId": {
"type": "number",
"description": "GeoNames feature id of the water body. Absent when GeoNames has none."
}
},
"description": "The ocean or sea at the point; present only when no country contains it or lies within coastalBufferKm.",
"additionalProperties": false
},
"shown": {
"type": "number",
"description": "Nearby places or features returned."
},
"nearby": {
"type": "array",
"items": {
"type": "object",
"required": [
"geonameId",
"name",
"toponymName"
],
"properties": {
"lat": {
"type": "number",
"description": "Latitude in decimal degrees. Absent when GeoNames sent none."
},
"lng": {
"type": "number",
"description": "Longitude in decimal degrees. Absent when GeoNames sent none."
},
"name": {
"type": "string",
"description": "Name of the place or feature, as GeoNames displays it."
},
"geonameId": {
"type": "number",
"description": "GeoNames feature id: pass it to geonames_get_place or geonames_get_hierarchy."
},
"adminName1": {
"type": "string",
"description": "Name of the first-order admin division containing it."
},
"population": {
"type": "number",
"description": "Population. Absent when GeoNames records none."
},
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 code of the containing country."
},
"featureCode": {
"type": "string",
"description": "Feature code, such as PPL (populated place), PPLX (section), PPLH (historical place), or MT (mountain)."
},
"featureName": {
"type": "string",
"description": "GeoNames' name for the feature code."
},
"toponymName": {
"type": "string",
"description": "GeoNames' main name for the feature, often the local-language form."
},
"distanceInKm": {
"type": "number",
"description": "Distance from the point in kilometres. Absent when GeoNames sent no usable value."
},
"featureClass": {
"type": "string",
"description": "One-letter feature class (P populated place, T terrain, H water, …)."
}
},
"description": "One nearby place or feature.",
"additionalProperties": false
},
"description": "Nearest places or features, nearest first; empty when nearbyKind is none."
},
"notice": {
"type": "string",
"description": "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, and past 50 the geonames_search_places call that lists the rest), or no IANA timezone covers it."
},
"country": {
"type": "object",
"required": [
"countryCode"
],
"properties": {
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code."
},
"countryName": {
"type": "string",
"description": "Country name. Absent when GeoNames sent none."
},
"distanceInKm": {
"type": "number",
"description": "Kilometres from the point to this country as GeoNames maps it, to the metre. Present only when no country contains the point and this one was matched within coastalBufferKm."
}
},
"description": "The country containing the point, or with coastalBufferKm the nearest country within that distance (then distanceInKm is set); absent offshore and in unmapped areas.",
"additionalProperties": false
},
"timezone": {
"type": "object",
"required": [
"rawOffsetInHours",
"gmtOffsetInHours",
"dstOffsetInHours"
],
"properties": {
"sunset": {
"type": "string",
"description": "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."
},
"sunrise": {
"type": "string",
"description": "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."
},
"localTime": {
"type": "string",
"description": "Current local time, YYYY-MM-DD HH:mm. Absent offshore."
},
"timezoneId": {
"type": "string",
"description": "IANA timezone id, such as Europe/Paris. Absent offshore."
},
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 code of the timezone country. Absent offshore."
},
"dstOffsetInHours": {
"type": "number",
"description": "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."
},
"gmtOffsetInHours": {
"type": "number",
"description": "UTC offset in hours on 1 January of the current local year."
},
"rawOffsetInHours": {
"type": "number",
"description": "Standard UTC offset in hours, without DST."
}
},
"description": "The timezone at the point; present only with includeTimezone.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when more places or features lie within the radius than nearby holds."
},
"nearbyKind": {
"enum": [
"populated_places",
"features",
"none"
],
"type": "string",
"description": "What nearby lists: populated_places, features (featureClasses or featureCodes was set), or none (nearbyLimit 0)."
},
"adminLevels": {
"type": "array",
"items": {
"type": "object",
"required": [
"level"
],
"properties": {
"code": {
"type": "string",
"description": "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."
},
"name": {
"type": "string",
"description": "Name of the division."
},
"level": {
"type": "number",
"description": "Admin level: 1 for the first-order division, up to 5."
},
"isoCode": {
"type": "string",
"description": "ISO 3166-2 code of the division, subdivision part only (IDF, not FR-IDF), where one exists."
},
"geonameId": {
"type": "number",
"description": "GeoNames feature id of the division: pass it to geonames_get_place."
}
},
"description": "One admin division containing the point, or for a country matched within coastalBufferKm, the one nearest it.",
"additionalProperties": false
},
"description": "Admin 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."
}
},
"additionalProperties": false
}geonames_reverse_geocode annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}geonames_find_postal_codes — Find GeoNames postal codes
Advertised read-onlyOpen-world
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.
geonames_find_postal_codes input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"mode"
],
"properties": {
"lat": {
"type": "number",
"maximum": 90,
"minimum": -90,
"description": "Latitude in decimal degrees, -90 to 90. Required in mode nearby."
},
"lng": {
"type": "number",
"maximum": 180,
"minimum": -180,
"description": "Longitude in decimal degrees, -180 to 180. Required in mode nearby."
},
"mode": {
"enum": [
"code",
"place_name",
"nearby"
],
"type": "string",
"description": "What to look up. code: the place for postalCode (required). place_name: the postal codes of placeName (required). nearby: postal codes around lat and lng (both required; countries not accepted)."
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 1000,
"minimum": 1,
"description": "Maximum entries to return, 1 to 1,000. This tool returns at most 100 per call: a larger limit is held to 100, and the notice says so when more entries remain. Default 10."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 5000,
"minimum": 0,
"description": "Postal codes to skip before the first one returned, 0 to 5000. Default 0. Modes code and place_name only; pass the nextOffset of the previous page to read the next one."
},
"radiusKm": {
"type": "number",
"default": 10,
"maximum": 30,
"description": "Search radius in kilometres for mode nearby, above 0 and at most 30 (GeoNames' free-tier limit). Default 10.",
"exclusiveMinimum": 0
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^([A-Z]{2,3}|\\d{3})$",
"description": "ISO 3166-1 alpha-2, alpha-3, or three-digit numeric country code."
},
"maxItems": 10,
"description": "Countries to look up postal codes in: ISO 3166-1 codes, up to 10, as a list: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. UK is accepted for GB and FL for LI. A listed country also returns the territories GeoNames files under it (GB also returns IM, JE, and GG), each postal code's countryCode naming its own country. Modes code and place_name only."
},
"placeName": {
"type": "string",
"maxLength": 100,
"description": "Place name to find postal codes for, up to 100 characters. GeoNames matches it against place, admin, and country names. Required in mode place_name; in mode code it narrows the match; not used in mode nearby."
},
"postalCode": {
"type": "string",
"pattern": "^[A-Z0-9][A-Z0-9 -]{0,11}$",
"description": "Postal code to resolve, such as 98101, SW1A 1AA, or K1A 0A1: capital letters, digits, spaces, and hyphens, up to 12 characters. Required in mode code; in mode place_name it narrows the match; not used in mode nearby."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Your 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."
}
},
"additionalProperties": false
}geonames_find_postal_codes output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"mode",
"postalCodes",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit applied: limit as given, or 100 when it asked for more."
},
"mode": {
"enum": [
"code",
"place_name",
"nearby"
],
"type": "string",
"description": "The lookup mode that ran."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"mode_fields_mismatch",
"unknown_country_code",
"username_required",
"caller_account_rejected",
"server_account_rejected",
"quota_exhausted",
"upstream_rejected_parameter"
],
"description": "Machine-readable failure mode. Declared by this tool: `mode_fields_mismatch`: A field the mode requires is missing, or countries is given or offset above 0 in mode nearby. The message names the field. `unknown_country_code`: A countries entry, once mapped to alpha-2, is none of the 250 country codes or the retired AN, CS, and YU: an alpha-2 such as EL or EU, or an unassigned alpha-3 or numeric code. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Postal codes returned on this page."
},
"notice": {
"type": "string",
"description": "Guidance: why nothing matched or nothing lies at offset, or how to reach the postal codes past this page (naming a limit held to 100), and which postal codes on the page lie in countries that countries does not list."
},
"truncated": {
"type": "boolean",
"description": "True when more postal codes remain past this page; in mode nearby, more lie within radiusKm."
},
"nextOffset": {
"type": "number",
"description": "Offset of the next page in modes code and place_name; absent on the last page, in mode nearby, and once offset is 5000. Capped at 5000, the last offset GeoNames' free service accepts, so that page can repeat rows of this one."
},
"postalCodes": {
"type": "array",
"items": {
"type": "object",
"required": [
"postalCode",
"placeName",
"countryCode"
],
"properties": {
"lat": {
"type": "number",
"description": "Latitude of the postal code's centroid in decimal degrees. In mode nearby, the first US row is the query point itself (GeoNames resolves it from ZIP-code areas). Absent when GeoNames sent none."
},
"lng": {
"type": "number",
"description": "Longitude of the postal code's centroid in decimal degrees; same caveat as lat. Absent when GeoNames sent none."
},
"iso3166_2": {
"type": "string",
"description": "ISO 3166-2 code of the first-order admin division, subdivision part only: MO, not US-MO. Not sent in mode nearby."
},
"placeName": {
"type": "string",
"description": "Place the postal code serves."
},
"adminCode1": {
"type": "string",
"description": "First-order admin division code (state, province) as the postal dataset records it, which can differ from the gazetteer code geonames_search_places filters on: DE 80331 carries BY here, where the gazetteer codes Bavaria 02. Not a geonames_search_places filter; for the gazetteer codes, call geonames_reverse_geocode at the row's lat and lng."
},
"adminCode2": {
"type": "string",
"description": "Second-order admin division code (county, district) as the postal dataset records it, which can differ from the gazetteer code (Greater London rows carry 11609024, GLA, or E99999999). Not a geonames_search_places filter."
},
"adminCode3": {
"type": "string",
"description": "Third-order admin division code as the postal dataset records it. Not a geonames_search_places filter."
},
"adminName1": {
"type": "string",
"description": "First-order admin division name."
},
"adminName2": {
"type": "string",
"description": "Second-order admin division name."
},
"adminName3": {
"type": "string",
"description": "Third-order admin division name."
},
"postalCode": {
"type": "string",
"description": "The postal code, as GeoNames stores it."
},
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 country code."
},
"distanceInKm": {
"type": "number",
"description": "Distance from the query point in kilometres. Mode nearby only; absent when GeoNames sent none."
}
},
"description": "One postal code.",
"additionalProperties": false
},
"description": "Matching postal codes on this page; nearest first in mode nearby."
}
},
"additionalProperties": false
}geonames_find_postal_codes annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}geonames_get_countries — GeoNames country facts
Advertised read-onlyOpen-world
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.
geonames_get_countries input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"limit": {
"type": "integer",
"default": 50,
"maximum": 1000,
"minimum": 1,
"description": "Maximum entries to return, 1 to 1,000. This tool returns at most 250 per call: a larger limit is held to 250, and the notice says so when more entries remain. Default 50."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries to skip before the first one returned, for paging. Default 0."
},
"continent": {
"enum": [
"AF",
"AN",
"AS",
"EU",
"NA",
"OC",
"SA"
],
"type": "string",
"description": "Keep only countries on this continent: AF Africa, AN Antarctica, AS Asia, EU Europe, NA North America, OC Oceania, SA South America."
},
"countries": {
"type": "array",
"items": {
"type": "string",
"pattern": "^([A-Z]{2,3}|\\d{3})$",
"description": "ISO 3166-1 alpha-2, alpha-3, or three-digit numeric country code."
},
"maxItems": 250,
"description": "Countries to return by ISO 3166-1 code: alpha-2 (US), alpha-3 (USA), or three-digit numeric (840), up to 250, as a list. UK is accepted for GB and FL for LI. Match country names with nameContains instead."
},
"nameContains": {
"type": "string",
"maxLength": 100,
"description": "Keep only countries whose English name contains every word of this text as a substring (niger also matches Nigeria), ignoring case, accents, and punctuation. Give at least one letter or digit."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Your own GeoNames username, spent only when the country table is not already cached, so the call uses that account's credit instead of the server's. The account needs free web services enabled on its geonames.org account page."
}
},
"additionalProperties": false
}geonames_get_countries output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"countries",
"notFound",
"totalCount",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit applied: limit as given, or 250 when it asked for more."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"name_contains_unsearchable",
"username_required",
"caller_account_rejected",
"server_account_rejected",
"quota_exhausted",
"upstream_rejected_parameter"
],
"description": "Machine-readable failure mode. Declared by this tool: `name_contains_unsearchable`: nameContains is not blank but holds no letter or digit (only punctuation, symbols, emoji, or invisible characters), so it would match every country. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Countries returned on this page."
},
"notice": {
"type": "string",
"description": "Guidance when nothing matched, the offset is past the end, or more pages remain (naming a limit held to 250)."
},
"notFound": {
"type": "array",
"items": {
"type": "string",
"description": "A requested code."
},
"description": "Requested codes that match no GeoNames country; empty when every code matched."
},
"countries": {
"type": "array",
"items": {
"type": "object",
"required": [
"countryCode",
"isoAlpha3",
"countryName",
"geonameId",
"continentCode",
"continentName",
"languages",
"boundingBox"
],
"properties": {
"capital": {
"type": "string",
"description": "Capital city name. Absent where GeoNames gives none."
},
"fipsCode": {
"type": "string",
"description": "FIPS 10-4 country code. Absent where GeoNames gives none."
},
"geonameId": {
"type": "number",
"description": "The country's GeoNames feature id: pass it to geonames_get_children for its first-level divisions, or to geonames_get_place."
},
"isoAlpha3": {
"type": "string",
"description": "ISO 3166-1 alpha-3 code."
},
"languages": {
"type": "array",
"items": {
"type": "string",
"description": "A language tag such as en-US or haw."
},
"description": "Languages spoken, most used first, as GeoNames lists them."
},
"areaInSqKm": {
"type": "number",
"description": "Area in square kilometres. Absent where GeoNames gives none."
},
"isoNumeric": {
"type": "string",
"description": "ISO 3166-1 numeric code. Absent where ISO assigns none (Kosovo) or GeoNames gives none."
},
"population": {
"type": "number",
"description": "Population as GeoNames records it. Absent where GeoNames gives none."
},
"boundingBox": {
"type": "object",
"required": [
"north",
"south",
"east",
"west"
],
"properties": {
"east": {
"type": "number",
"description": "Eastern longitude bound, decimal degrees."
},
"west": {
"type": "number",
"description": "Western longitude bound, decimal degrees."
},
"north": {
"type": "number",
"description": "Northern latitude bound, decimal degrees."
},
"south": {
"type": "number",
"description": "Southern latitude bound, decimal degrees."
}
},
"description": "Bounding box of the country's mainland.",
"additionalProperties": false
},
"countryCode": {
"type": "string",
"description": "ISO 3166-1 alpha-2 code."
},
"countryName": {
"type": "string",
"description": "GeoNames' English country name."
},
"currencyCode": {
"type": "string",
"description": "ISO 4217 currency code. Absent where GeoNames gives none."
},
"continentCode": {
"type": "string",
"description": "Continent code: AF, AN, AS, EU, NA, OC, or SA."
},
"continentName": {
"type": "string",
"description": "Continent name."
},
"postalCodeFormat": {
"type": "string",
"description": "Postal-code pattern (# a digit, @ a letter). Absent for countries without postal codes."
}
},
"description": "One country.",
"additionalProperties": false
},
"description": "Countries on this page, in GeoNames order (by alpha-2 code)."
},
"truncated": {
"type": "boolean",
"description": "True when more countries remain past this page."
},
"nextOffset": {
"type": "number",
"description": "Offset of the next page; absent on the last page."
},
"totalCount": {
"type": "number",
"description": "Countries matching the filters, before paging."
}
},
"additionalProperties": false
}geonames_get_countries annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}geonames_list_reference — GeoNames reference vocabulary
Advertised read-onlyOpen-world
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).
geonames_list_reference input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"topic"
],
"properties": {
"limit": {
"type": "integer",
"default": 100,
"maximum": 1000,
"minimum": 1,
"description": "Maximum entries to return, 1 to 1,000. This tool returns at most 700 per call: a larger limit is held to 700, and the notice says so when more entries remain. Default 100."
},
"topic": {
"enum": [
"feature_classes",
"feature_codes",
"postal_countries"
],
"type": "string",
"description": "Vocabulary to list: feature_classes (the 9 one-letter classes), feature_codes (the 684 codes), or postal_countries (countries with postal-code data)."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Entries to skip before the first one returned, for paging. Default 0."
},
"featureClass": {
"enum": [
"A",
"H",
"L",
"P",
"R",
"S",
"T",
"U",
"V"
],
"type": "string",
"description": "Topic feature_codes only: keep the codes of this one-letter class (A, H, L, P, R, S, T, U, V)."
},
"nameContains": {
"type": "string",
"maxLength": 100,
"description": "Keep only entries whose code, name, or description contains every word of this text as a substring (port also matches airport), ignoring case, accents, and punctuation. Give at least one letter or digit."
},
"geonamesUsername": {
"type": "string",
"pattern": "^\\S{1,64}$",
"description": "Topic postal_countries only, and only when the list is not already cached: your own GeoNames username, so the call spends that account's credit instead of the server's. The account needs free web services enabled on its geonames.org account page."
}
},
"additionalProperties": false
}geonames_list_reference output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"topic",
"entries",
"totalCount",
"truncated",
"shown",
"cap"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit applied: limit as given, or 700 when it asked for more."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"filter_not_applicable",
"name_contains_unsearchable",
"username_required",
"caller_account_rejected",
"server_account_rejected",
"quota_exhausted",
"upstream_rejected_parameter"
],
"description": "Machine-readable failure mode. Declared by this tool: `filter_not_applicable`: featureClass was given with a topic other than feature_codes. `name_contains_unsearchable`: nameContains is not blank but holds no letter or digit (only punctuation, symbols, emoji, or invisible characters), so it would match every entry. `username_required`: Neither geonamesUsername nor the server's GEONAMES_USERNAME supplies a GeoNames account. `caller_account_rejected`: GeoNames rejected the caller-supplied geonamesUsername (unknown user, or free web services not enabled). `server_account_rejected`: GeoNames rejected the server's GEONAMES_USERNAME. `quota_exhausted`: GeoNames reported the account's hourly, daily, or weekly credit limit spent, or this server's pacer for the account shed the call. `upstream_rejected_parameter`: GeoNames rejected a value the schema let through; the message carries its text. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Entries returned on this page."
},
"topic": {
"enum": [
"feature_classes",
"feature_codes",
"postal_countries"
],
"type": "string",
"description": "The topic listed."
},
"notice": {
"type": "string",
"description": "Guidance when nothing matched, the offset is past the end, or more pages remain (naming a limit held to 700)."
},
"entries": {
"type": "array",
"items": {
"type": "object",
"required": [
"code",
"name"
],
"properties": {
"code": {
"type": "string",
"description": "Feature class letter, feature code without its class prefix (PPLC), or ISO 3166-1 alpha-2 country code."
},
"name": {
"type": "string",
"description": "GeoNames' label: the class label, the feature code's name, or the country name."
},
"description": {
"type": "string",
"description": "The class's category and code count, or GeoNames' definition of the feature code. Absent where GeoNames gives none."
},
"featureClass": {
"enum": [
"A",
"H",
"L",
"P",
"R",
"S",
"T",
"U",
"V"
],
"type": "string",
"description": "Topic feature_codes: the class the code belongs to."
},
"maxPostalCode": {
"type": "string",
"description": "Topic postal_countries: the highest postal code or prefix GeoNames holds."
},
"minPostalCode": {
"type": "string",
"description": "Topic postal_countries: the lowest postal code or prefix GeoNames holds."
},
"postalCodeCount": {
"type": "number",
"description": "Topic postal_countries: how many postal codes GeoNames holds for the country."
}
},
"description": "One vocabulary entry.",
"additionalProperties": false
},
"description": "Entries on this page, in GeoNames order."
},
"truncated": {
"type": "boolean",
"description": "True when more entries remain past this page."
},
"nextOffset": {
"type": "number",
"description": "Offset of the next page; absent on the last page."
},
"totalCount": {
"type": "number",
"description": "Entries matching the topic and filters, before paging."
}
},
"additionalProperties": false
}geonames_list_reference annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}Prompts
0 advertised
Resources
1 advertised
geonames-guide
Gates and identifier crossings for the geonames_* gazetteer tools. Covers moving from a postal code to gazetteer admin codes and geonameIds, a town's complete postal-code list, a city that exists as two features with two populations, ranking or summing places by population, searching inside a state or county, microstates, nearest-place lists that stop at a cap, and the timezone at a coordinate. Use before counting, ranking, or chaining geonames_* results.
geonames-guide URI
skill://geonames-guide/SKILL.mdio.modelcontextprotocol/skills
io.modelcontextprotocol/skills URI template
skill://{+path}90-day uptime
A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.
- 2026-11-07: 1 of 1 checks answered
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 638 ms
- 95th percentile latency
- 638 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 638 ms · metadata changed · 8 tool(s), 1 resource(s), 1 resource template(s), 0 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http geonames-mcp-server-caseyjhand https://geonames.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add geonames-mcp-server-caseyjhand --url https://geonames.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"geonames-mcp-server-caseyjhand": {
"url": "https://geonames.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"geonames-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://geonames.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"geonames-mcp-server-caseyjhand": {
"type": "http",
"url": "https://geonames.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http geonames-mcp-server-caseyjhand https://geonames.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
https://geonames.caseyjhand.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"geonames-mcp-server-caseyjhand": {
"serverUrl": "https://geonames.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like geonames-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.