geonames-mcp-server

Search GeoNames places

geonames_search_places

Read-onlyIdempotent

Search the GeoNames gazetteer of 13M+ places by name and filters: country, 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.

Input Schema

TableJSON Schema

Name	Required	Description
`limit`	No	Maximum entries to return, 1 to 100. Default 10.
`match`	No	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. Case-insensitive.
`query`	No	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`	No	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. Beside featureClasses or featureCodes, list only class P or class-P codes such as PPLC. Case-insensitive.
`offset`	No	Entries to skip before the first one returned, for paging, 0 to 5000. Default 0.
`orderBy`	No	Result order: relevance (GeoNames' default) or population, largest first. Case-insensitive.
`countries`	No	ISO 3166-1 country codes, up to 10, as a list or a comma-separated string: alpha-2 (US, GB, DE), alpha-3 (USA, GBR, DEU), or three-digit numeric (840, 826, 276), each sent to GeoNames as alpha-2. Case-insensitive; UK is accepted for GB.
`boundingBox`	No	Keep only places inside this box. The box cannot cross the 180° meridian: split such an area into two searches.
`featureCodes`	No	GeoNames feature codes (PPLC capital, ADM1 state, MT mountain, AIRP airport), up to 20, as a list or a comma-separated string. Case-insensitive; a class prefix (P.PPLC) 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.
`featureClasses`	No	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. 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.
`geonamesUsername`	No	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.

Output Schema

TableJSON Schema

Name	Required	Description
`cap`	No	The limit that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Places returned on this page.
`notice`	No	Guidance when nothing matched or more pages remain.
`places`	No	Places on this page, in the requested order.
`truncated`	No	True when more matching places remain past this page.
`nextOffset`	No	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`	No	GeoNames' count of matching places, before paging.
`effectiveQuery`	No	The match mode, query, and filters as the server sent them to GeoNames.

Schema Changelog

Changes observed during successful MCP inspections.

First observedOct 2, 2026

TDQS

A4.1/5.0

Behavior4/5

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

Annotations already declare readOnly/openWorld/idempotent, so the safety profile is covered; the description adds real value beyond that by disclosing cost ('1 GeoNames credit per call') and the default name-matching behavior that shapes results. It does not mention result pagination limits or ranking caveats, but those live in the schema.

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 purpose and filter list, then the practical matching note and cost. It is dense but each clause carries meaning; the parenthetical feature-class/code examples are the only slightly redundant element given full schema coverage.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For an 11-parameter, nested-schema tool with an output schema and annotations, the description supplies the decision-relevant extras (credit cost, default match behavior, filter-only requirement) and does not need to explain return values. Only the absence of explicit alternative-tool routing keeps it from a 5.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all 11 parameters in detail; the baseline is 3. The description's glosses (P populated places, PPLC capitals, population tier) add a small amount of orienting context but largely restate what the schema already says.

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 ('Search the GeoNames gazetteer of 13M+ places') and enumerates the filter dimensions, so an agent knows exactly what this tool retrieves. It also names the sibling tools (geonames_get_place, geonames_get_hierarchy, geonames_get_children) that consume its geonameId output, which separates it from those id-based lookups.

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?

Explains the default match semantics ('Berlin, Germany' pattern) and the filter-only fallback, which tells the agent how to frame a call. It does not explicitly route the agent away from siblings like geonames_reverse_geocode when coordinates (not names) are the input, so it stops short of full when-not guidance.

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 tools Inspect

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.