OpenCage Geocoding MCP Server

OpenCage 地理编码 MCP 服务

一个 MCP（Model Context Protocol）服务，使用 OpenCage 地理编码 API 提供地理编码功能。 此服务可在地址与地理坐标之间进行转换。

**请注意：**此处的示例基于与 claude.ai 桌面客户端的集成。其他服务也支持 MCP，但可能需要稍有不同的配置。

功能

• 正向地理编码：将地址或地点名称转换为坐标（纬度/经度）
• 反向地理编码：将坐标转换为地址
• API 状态监控：检查 API 使用情况和速率限制（假设你的 penCage 账户设置了硬性限制）。

前置条件

1. Node.js（版本 20 或更高）
2. OpenCage 地理编码 API 密钥：在 OpenCage 网站 注册，获取免费的试用地理编码 API 密钥

安装

0. MCP 是合适的工具吗？

   此 MCP 适用于少量地理编码任务，例如手动向大模型提供提示词时使用。

   但如果你想处理大量数据，例如包含地址或坐标的 CSV 文件，或连接到包含大量数据的数据库，使用我们的命令行工具几乎肯定会更快、更实惠；你也可以让大模型编写脚本，直接调用我们的 API。

   我们提供采用 Markdown 格式的 opencage-geocoding-api SKILL 文件，用于训练 AI，使其掌握使用我们的地理编码 API 的最佳实践。

1. 克隆代码库。进入代码库目录

git clone [email protected]:OpenCageData/opencage-geocoding-mcp.git
# or
git clone https://github.com/OpenCageData/opencage-geocoding-mcp.git

cd opencage-geocoding-mcp

2. 安装依赖项：

npm install

这样就足以让 MCP 在 Claude Desktop 中运行（见下文）

如果你想开发此 MCP，并计划从命令行查询 MCP， 还需要：

3. 将 OpenCage 地理编码 API 密钥设置为环境变量：

export OPENCAGE_API_KEY="your_opencage_geocoding_api_key_here"

4. 构建项目：

npm run build

使用方法

在 Claude Desktop 中使用

将此配置添加到 Claude Desktop 配置文件中

在 Mac 上，配置文件应为（~/Library/Application Support/Claude/claude_desktop_config.json），也可以通过菜单导航到该文件：Settings > Developer > Edit Config

{
  "mcpServers": {
    "opencage-geocoding": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/opencage-geocoding-mcp/build/index.js"],
      "env": {
        "OPENCAGE_API_KEY": "your_opencage_geocoding_api_key_here"
      }
    }
  }
}

可用工具

注意：首次运行命令时，需要授予 Claude 权限

1. geocode-forward

将地址或地点名称转换为坐标及该地点的相关信息。

参数：

• query（必填）：要进行地理编码的地址或地点名称
• countrycode（可选）：限定国家/地区（ISO 3166-1 alpha-2 代码）
• bounds（可选）：边界框（min_lon,min_lat,max_lon,max_lat）
• language（可选）：结果语言（例如，'en'、'de'、'fr'）
• limit（可选）：最多返回结果数（1-100，默认值为 10）
• no_annotations（可选）：排除位置注释

提示词示例

Prompt: "What are the coordinates of Trafalgar Square, London?"
Result: coordinates, timezone, local currency, etc

Prompt: "Where is Les Vans, France? Which Department is it in?"
Result: coordinates, and correct answer that Les Vans is in the Ardèche department

Prompt: "In welchem Bundesland liegt Weimar?"
Result: coordinates, and correct answer that Weimar is in Thüringen

2. geocode-reverse

将坐标转换为地址及该地点的相关信息

参数：

• latitude（必填）：十进制格式的纬度坐标（-90 至 90）
• longitude（必填）：十进制格式的经度坐标（-180 至 180）
• language（可选）：结果语言
• no_annotations（可选）：排除位置注释

提示词示例

Prompt: "what is the address at 38.8976, -77.0365?"
Result: "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States of America"

Prompt: "Which province are the coordinates 41.38700, 2.16995 in?"
Result: "Coordinates are in Barcelona in the province of Catalonia"

3. get-opencage-info

检查当前的 API 使用情况和速率限制。 注意：订阅用户没有硬性使用限制。请参阅相关文档。

**参数：**无

**返回：**剩余请求次数、速率限制和重置时间等信息。

可用提示词

geocoding-assistant

用于地理编码任务的实用助手。提供有关如何有效使用地理编码工具的指导。

错误处理

服务器包含全面的错误处理机制：

• API 密钥无效
• 超出速率限制
• 网络错误
• 坐标或地址无效
• API 服务不可用

环境变量

• OPENCAGE_API_KEY：你的 OpenCage 地理编码 API 密钥（必需）

故障排除

1. “需要 API 密钥”错误：确保已设置环境变量 OPENCAGE_API_KEY
2. “未找到结果”：尝试使用更具体的地址或其他地址格式，参见 OpenCage 查询格式指南
3. 速率限制错误：使用 get-api-status 工具检查 API 使用情况
4. 网络错误：检查互联网连接，或访问 OpenCage 公共状态页面

相关链接

• OpenCage 主页 - 获取地理编码 API 密钥

• OpenCage API 文档 - 完整的 OpenCage 地理编码 API 参考

• OpenCage MCP 教程

• 模型上下文协议 - 了解更多关于 MCP 的信息

OpenCage GmbH 是谁？

我们运营全球范围的地理编码 API和地理搜索服务，基于开放数据构建。 了解更多关于我们。

我们还组织 Geomob，这是面向位置服务创作者的一系列定期聚会，我们会尽力展示地理领域的创新。如果你喜欢地理相关内容，可能会喜欢 Geomob 播客。