内容
# @apogeoapi/mcp
适用于 [ApogeoAPI](https://app.apogeoapi.com) 的 MCP（模型上下文协议）服务器，提供地理数据、实时汇率和 IP 地理位置信息，适用于 Claude Desktop、Cursor 以及任何兼容 MCP 的 AI 助手。
## 功能描述
该服务器将 ApogeoAPI 的 REST 端点暴露为 AI 助手可以直接调用的工具。询问 Claude “当前阿根廷的美元汇率是多少？”或“对 IP 地址 8.8.8.8 进行地理定位”，它将自动调用正确的工具。
## 可用工具
| 工具 | 描述 | 计划要求 |
|------|-------------|---------------|
| `get_country` | 通过 ISO2/ISO3 代码获取完整的国家/地区数据 - 名称、首都、地区、人口、货币、实时美元汇率、时区、电话代码 | 免费 |
| `list_countries` | 所有 250+ 个国家的分页列表 | 免费 |
| `search_countries` | 通过部分名称搜索国家/地区 | 免费 |
| `get_states` | 一个国家/地区的所有州/省 | 基础+ |
| `get_cities` | 通过数字州 ID 获取一个州的所有城市 | 基础+ |
| `get_currency_rate` | 一个国家/地区货币的实时美元汇率（每 4 小时更新一次） | 基础+ |
| `geolocate_ip` | 任意 IPv4/IPv6 的国家/地区、地区、城市、坐标、时区和欧盟成员资格 | 基础+ |
| `global_search` | 在一个查询中搜索国家/地区、州和城市 | 免费 |
## 安装
### Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json` 文件中：
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
```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` 下添加相同的块。
### 手动构建
```bash
git clone https://github.com/APOGEOAPI/apogeoapi-mcp.git
cd apogeoapi-mcp
npm install
npm run build
```
然后直接引用已构建的文件：
```json
{
"mcpServers": {
"apogeoapi": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.js"],
"env": {
"APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}
```
## 获取 API 密钥
1. 在 [app.apogeoapi.com](https://app.apogeoapi.com) 上创建一个免费账户
2. 进入 **API 密钥** 并生成一个新的密钥
3. 将密钥粘贴到上面的 `APOGEOAPI_KEY` 环境变量中
免费计划（1,000 次请求/月）不需要信用卡。
## 计划要求
| 功能 | 免费 | 基础 ($19/月) | 入门 ($29/月) | 专业 ($79/月) |
|---------|------|----------------|-------------------|-----------------------|
| 国家/地区（列表、搜索、获取） | 是 | 是 | 是 | 是 |
| 全局搜索 | 是 | 是 | 是 | 是 |
| 州和城市 | 否 | 是 | 是 | 是 |
| 实时货币汇率 | 否 | 是 | 是 | 是 |
| IP 地理位置 | 否 | 是 | 是 | 是 |
| 每月请求 | 1,000 | 15,000 | 100,000 | 500,000 |
在 [app.apogeoapi.com/dashboard/billing](https://app.apogeoapi.com/dashboard/billing) 升级。
## 环境变量
| 变量 | 必需 | 描述 |
|----------|----------|-------------|
| `APOGEOAPI_KEY` | 是 | 从仪表盘获取的 API 密钥 |
| `APOGEOAPI_BASE_URL` | 否 | 覆盖 API 基础 URL（默认：`https://api.apogeoapi.com`） |
## 许可证
MIT
