geomelon-mcp

MCP server for the Geomelon geographic API. Exposes cities, countries, regions, and languages as tools any MCP-compatible AI client can call.

Looking for other ways to integrate? See all official libraries at geomelon.dev/libraries.

Two transports are included:

Binary	Transport	Use case
`geomelon-mcp`	stdio	Claude Desktop, Cursor, Cline, Continue
`geomelon-mcp-http`	HTTP (Streamable)	Claude Code, remote / hosted server

Requirements

Node.js 18+
A RapidAPI key with the Geomelon API subscribed — optional, see keyless demo mode below

Keyless demo mode

No GEOMELON_API_KEY? Run the server anyway — it starts up with just the search_cities_autocomplete tool, backed by the free oneshot host, no signup required. Every other tool needs a key. This is the fastest way to try the server before subscribing on RapidAPI.

Try it with zero setup

Geomelon also runs a public hosted instance of this same keyless demo — no npx, no local process. Point any remote-MCP-capable client (Claude web/desktop connectors, ChatGPT connectors, MCP Inspector, etc.) at:

https://mcp.geomelon.dev/mcp

It exposes only search_cities_autocomplete, same as running the server yourself with no API key. For the full 22-tool set, run your own instance (below) with your RapidAPI key.

Claude Code (HTTP)

Create a .env file in the directory you'll run the server from:

cp .env.example .env
# then edit .env and set GEOMELON_API_KEY

Start the server (dotenv loads .env automatically):

npx geomelon-mcp-http

claude mcp add --transport http geomelon http://localhost:3000/mcp

Verify it's connected:

claude mcp list

The server must be running whenever you use Claude Code. To use a different port set PORT=your_port and update the URL in the claude mcp add command accordingly.

Claude Desktop (stdio)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "geomelon": {
      "command": "npx",
      "args": ["-y", "geomelon-mcp"],
      "env": {
        "GEOMELON_API_KEY": "your_rapidapi_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving.

Cursor / Windsurf / Cline (stdio)

Add to your editor's MCP config:

{
  "geomelon": {
    "command": "npx",
    "args": ["-y", "geomelon-mcp"],
    "env": {
      "GEOMELON_API_KEY": "your_rapidapi_key_here"
    }
  }
}

Remote / hosted HTTP server

Create a .env file on your server:

cp .env.example .env
# set GEOMELON_API_KEY and PORT in .env

Start the server:

npx geomelon-mcp-http

Then register with any MCP client using http://your-host:3000/mcp as the URL.

The HTTP transport is stateless — each request is independent, no session management needed. CORS is wide open (Access-Control-Allow-Origin: *) since this transport is meant to be reachable by browser-based remote-MCP clients too. GET / (or /health) returns a small JSON status object — useful for uptime checks — reporting whether the instance has a key configured ("mode": "full" or "mode": "keyless-demo").

Available tools

Cities

Tool	Description
`search_cities`	Search by name, country code, region, population range, sort order
`get_city`	Full details for a city by UUID
`get_city_translations`	All name translations for a city by UUID
`get_city_settlement_types`	Settlement-type classifications for a city by UUID
`cities_by_coordinates_closest`	Cities nearest to a lat/lon, ordered by distance
`cities_by_coordinates_largest`	Largest cities near a lat/lon, ordered by population
`cities_distance`	Distance in km between two cities

Countries

Tool	Description
`list_countries`	List countries, filter by name prefix or telephone dialing code
`get_country`	Full details for a country by UUID (includes translations and regions)
`get_country_translations`	Name translations for a country by UUID
`get_country_regions`	All administrative regions for a country by UUID

Regions

Tool	Description
`list_regions`	List regions, filter by country UUID
`get_region`	Full details for a region by UUID
`get_region_translations`	Name translations for a region by UUID

Languages

Tool	Description
`list_languages`	List all languages in the database
`get_language`	Details for a language by UUID

Oneshot prefix search (free, no API key)

Tool	Description
`search_cities_autocomplete`	Country-scoped, language-specific city name prefix search backed by pre-built static files. The only tool available in keyless demo mode. Works in keyed mode too — it's the fastest search path.

See geomelon.dev/free-city-autocomplete-api for supported country/language pairs and the underlying HTTP endpoint.

Compound tools

These tools chain multiple API calls internally to save round-trips.

Tool	Description
`find_cities_near_city`	Given a city UUID, find nearby cities ordered by distance or population
`city_context`	Fetch a city together with its full country and region details in one call
`country_overview`	Fetch a country (by UUID or name), its regions, and top cities by population
`compare_cities`	Fetch two cities and the distance between them in one call
`search_cities_in_country`	Search cities using a country name instead of an ISO code

Geomelon

文件