Geonames MCP Server

What geonames-mcp-server MCP server does

The geonames-mcp-server MCP server exposes GeoNames data to MCP-compatible clients. GeoNames contains places worldwide, identified by stable integer geonameId values and organized into administrative relationships. The server supports searches by place name and geographic filters, detailed place records, parent and child relationships, coordinate lookups, postal-code queries, country information, and GeoNames reference data.

Results can include administrative levels, feature classes and codes, population, coordinates, elevation, time zones, alternate names, postal codes, external identifiers, and links. The available fields depend on the tool and the matching GeoNames record.

How it works

The server can run as a local STDIO process or as a Streamable HTTP service. A public hosted endpoint is also listed at https://geonames.casey jhand.com/mcp in the project material; use the exact published URL when configuring an HTTP client.

Place searches accept a query or filters such as country, feature class, feature code, population tier, or bounding box. A place ID can then be used to retrieve its full record, follow its hierarchy from Earth or a continent down to the feature, or list direct children. Reverse geocoding accepts latitude and longitude and can return the containing country, administrative subdivisions, nearby places or features, and optional time-zone details.

Setup and configuration

The documented package installation uses npx with @cyanheads/geonames-mcp-server. The server requires a GeoNames username through the GEONAMES_USERNAME environment variable. The repository provides setup links for Claude Desktop, Cursor, and VS Code, with the username included in the generated configuration.

Choose STDIO for a locally launched process or Streamable HTTP when the client connects to an HTTP endpoint. The project also publishes a Docker image, although the supplied material does not specify a complete Docker command or configuration example.

Tools and capabilities

The server provides eight tools:

• geonames_search_places searches by name or supported geographic filters, with pagination and relevance or population ordering.
• geonames_get_place retrieves one place record, including administrative data, time zone, elevation, alternate names, postal codes, and identifiers.
• geonames_get_hierarchy returns the parent chain for a place.
• geonames_get_children lists administrative, tourism, or dependency-tree children, with filtering and pagination.
• geonames_reverse_geocode resolves coordinates to countries, subdivisions, oceans, nearby places, or selected feature types.
• geonames_find_postal_codes searches postal codes by code, place name, or nearby coordinates.
• geonames_get_countries returns country facts and supports country, continent, and name filters.
• geonames_list_reference lists GeoNames feature classes, feature codes, and countries with postal-code data.

Limitations and notes

The geonames-mcp-server MCP server applies validation before some GeoNames requests. Search filters must use compatible feature classes and codes, country codes must be recognized, and bounding boxes must be valid. Reverse-geocoding filters cannot combine a city tier with feature filters. Postal-code coverage is reported for 122 countries; Ireland returns Eircode routing keys and Malta returns letter prefixes.

Child lookups fetch up to 1,000 children per parent and cache that result for subsequent filtering or pagination. GeoNames may report that more children exist. Postal-code searches do not provide a total count, so a full page is marked as truncated. Unknown place or country identifiers are represented in the tool results rather than treated as valid matches.