geomelon-mcp

geomelon-mcp

适用于 Geomelon 地理 API 的 MCP 服务。它将城市、国家、地区和语言作为工具提供，任何兼容 MCP 的 AI 客户端都可以调用这些工具。

想了解其他集成方式？请查看 geomelon.dev/libraries 上的所有官方库。

其中包含两种传输方式：

二进制文件	传输方式	使用场景
geomelon-mcp	stdio	Claude Desktop、Cursor、Cline、Continue
geomelon-mcp-http	HTTP（Streamable）	Claude Code、远程 / 托管服务

要求

• Node.js 18+
• 一个已订阅 Geomelon API 的 RapidAPI 密钥 — 可选，参见下方的无密钥演示模式

---

无密钥演示模式

没有 GEOMELON_API_KEY？仍可运行服务 — 启动后只提供 search_cities_autocomplete 工具，该工具由免费的 oneshot 主机提供支持，无需注册。其他所有工具都需要密钥。这是订阅 RapidAPI 之前试用服务的最快方式。

零配置试用

Geomelon 还运行着这个无密钥演示版的公共托管实例 — 无需 npx，也无需本地进程。将任何支持远程 MCP 的客户端（Claude 网页版 / 桌面版连接器、ChatGPT 连接器、MCP Inspector 等）指向：

https://mcp.geomelon.dev/mcp

它只提供 search_cities_autocomplete，与不提供 API 密钥时自行运行服务相同。如需使用完整的 22 个工具，请使用你的 RapidAPI 密钥运行自己的实例（如下）。

---

Claude Code（HTTP）

在你将运行服务的目录中创建 .env 文件：

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

启动服务（dotenv 会自动加载 .env）：

npx geomelon-mcp-http

将其注册到 Claude Code：

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

验证连接状态：

claude mcp list

使用 Claude Code 时，服务必须保持运行。如需使用其他端口，请设置 PORT=your_port，并相应更新 claude mcp add 命令中的 URL。

---

Claude Desktop（stdio）

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

保存后重启 Claude Desktop。

---

Cursor / Windsurf / Cline（stdio）

将以下内容添加到编辑器的 MCP 配置中：

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

---

远程 / 托管 HTTP 服务

在服务器上创建 .env 文件：

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

启动服务：

npx geomelon-mcp-http

然后使用 http://your-host:3000/mcp 作为 URL，在任意 MCP 客户端中注册该服务。

HTTP 传输是无状态的 — 每个请求彼此独立，无需管理会话。由于此传输方式也需要能被基于浏览器的远程 MCP 客户端访问，因此 CORS 对所有来源开放（Access-Control-Allow-Origin: *）。GET /（或 /health）会返回一个简短的 JSON 状态对象 — 可用于运行时间检查 — 其中会报告实例是否已配置密钥（"mode": "full" 或 "mode": "keyless-demo"）。

---

可用工具

城市

工具	描述
search_cities	按名称、国家代码、地区、人口范围和排序方式搜索
get_city	按 UUID 获取城市的完整详情
get_city_translations	按 UUID 获取城市名称的所有译名
get_city_settlement_types	按 UUID 获取城市的定居点类型分类
cities_by_coordinates_closest	获取距离某个经纬度最近的城市，按距离排序
cities_by_coordinates_largest	获取某个经纬度附近最大的城市，按人口排序
cities_distance	计算两座城市之间的距离（公里）

国家

工具	描述
list_countries	列出国家，可按名称前缀或电话区号筛选
get_country	按 UUID 获取国家的完整详情（包括译名和地区）
get_country_translations	按 UUID 获取国家名称的译名
get_country_regions	按 UUID 获取某个国家的所有行政区划

地区

工具	描述
list_regions	列出地区，可按国家 UUID 筛选
get_region	根据 UUID 获取地区的完整详情
get_region_translations	根据 UUID 获取地区名称的翻译

语言

工具	描述
list_languages	列出数据库中的所有语言
get_language	根据 UUID 获取语言详情

单次前缀搜索（免费，无需 API 密钥）

工具	描述
search_cities_autocomplete	按国家范围和语言筛选的城市名称前缀搜索，数据由预构建的静态文件提供。**这是无密钥演示模式中唯一可用的工具。**在使用密钥的模式下也可用——这是最快的搜索方式。

请参阅 geomelon.dev/free-city-autocomplete-api，了解支持的国家/语言组合和底层 HTTP 端点。

---

组合工具

这些工具会在内部串联多次 API 调用，以减少往返次数。

工具	描述
find_cities_near_city	给定城市 UUID，按距离或人口排序查找附近的城市
city_context	一次调用即可获取城市及其完整的国家和地区详情
country_overview	获取一个国家（按 UUID 或名称查找）、该国的地区，以及按人口排名靠前的城市
compare_cities	一次调用即可获取两个城市及其间的距离
search_cities_in_country	使用国家名称而非 ISO 代码搜索城市