ApogeoAPI

@apogeoapi/mcp

适用于 ApogeoAPI 的 MCP（Model Context Protocol）服务，为 Claude Desktop、Cursor 及任何兼容 MCP 的 AI 助手提供地理数据、实时汇率和 IP 地理定位。

功能

此服务将 ApogeoAPI 的 REST 端点开放为工具，供 AI 助手直接调用。向 Claude 提问“阿根廷当前的 USD 汇率是多少？”或“定位 IP 8.8.8.8”，它便会自动调用相应工具。

可用工具

工具	描述	所需套餐
get_country	根据 ISO2/ISO3 代码获取完整国家数据——名称、首都、地区、人口、货币、时区、电话区号（Basic+ 还提供实时 USD 汇率）	免费
list_countries	分页列出全部 250 多个国家	免费
search_countries	按部分名称搜索国家	免费
get_states	获取某个国家的所有州／省	免费
get_cities	根据数字州 ID 获取某个州的所有城市	Basic+
get_currency_rate	获取某个国家货币的实时 USD 汇率（每 4 小时更新）	Basic+
geolocate_ip	获取任意 IPv4/IPv6 的国家、地区、城市、坐标、时区及 EU 成员资格	Basic+
global_search	在一次查询中搜索国家、州和城市	Basic+

每个新账户都可免费完整使用 Basic+ 工具 14 天，无需信用卡。

所有工具均为只读，并声明 MCP 工具注解（readOnlyHint、destructiveHint、idempotentHint、openWorldHint），因此客户端无需确认提示即可运行这些工具。

安装

Claude Desktop

将以下内容添加到 claude_desktop_config.json：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "apogeoapi": {
      "command": "npx",
      "args": ["-y", "@apogeoapi/mcp"],
      "env": {
        "APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

保存文件后重启 Claude Desktop。ApogeoAPI 工具将显示在 Claude 的工具列表中。

Cursor

将相同的配置块添加到 Cursor 的 MCP 配置文件（~/.cursor/mcp.json）中的 mcpServers 下。

手动构建

git clone https://github.com/APOGEOAPI/apogeoapi-mcp.git
cd apogeoapi-mcp
npm install
npm run build

然后直接引用构建后的文件：

{
  "mcpServers": {
    "apogeoapi": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

获取 API 密钥

1. 在 app.apogeoapi.com 创建免费账户
2. 前往 API Keys 并生成新密钥
3. 将密钥粘贴到上方的 APOGEOAPI_KEY 环境变量中

Free 套餐（每月 1,000 次请求）无需信用卡。新账户可获得 14 天的完整使用权限。

套餐要求

功能	Free	Basic ($19/mo)	Starter ($29/mo)	Professional ($79/mo)
国家（列表、搜索、获取）	是	是	是	是
州和省	是	是	是	是
城市	14 天试用	是	是	是
全局搜索	14 天试用	是	是	是
实时汇率	14 天试用	是	是	是
IP 地理定位	14 天试用	是	是	是
每月请求数	1,000	15,000	100,000	500,000

前往 app.apogeoapi.com/dashboard/billing 升级。

环境变量

变量	必需	描述
APOGEOAPI_KEY	是	你在控制面板中获取的 API 密钥
APOGEOAPI_BASE_URL	否	覆盖 API 基础 URL（默认值：https://api.apogeoapi.com）

测试

npm test 会构建服务，通过 stdio 使用真实 MCP 客户端启动服务，并针对线上 API 调用每个工具。测试需要一个有权限访问所有工具的密钥（Basic+ 套餐或处于 14 天试用期内的账户）：

APOGEOAPI_KEY=your_key npm test

许可证

MIT