opencage-地理编码-MCP

Name: opencage-地理编码-MCP
Author: OpenCageData

作者：OpenCageData16 星标更新：2025-11-16

安装使用来源：spider==github.com

项目介绍

OpenCage 地理编码 MCP 服务器

一个基于模型上下文协议（MCP）的服务器，提供使用 OpenCage 地理编码 API 的地理编码功能。此服务器允许您在地址和地理坐标之间进行转换。

请注意： 以下示例基于与 claude.ai 桌面客户端的集成。MCP 作为一个概念被其他服务支持，但可能需要稍有不同的配置。

功能

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

前提条件

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

安装

git clone git@github.com:OpenCageData/opencage-geocoding-mcp.git
# 或者
git clone https://github.com/OpenCageData/opencage-geocoding-mcp.git

cd opencage-geocoding-mcp

安装依赖项：

npm install

这足以使 MCP 在 Claude Desktop 中运行（见下文）

如果您打算开发 MCP 并计划从命令行查询 MCP，还需要执行以下步骤：

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

export OPENCAGE_API_KEY="your_opencage_geocoding_api_key_here"

构建项目：

npm run build

使用

在 Claude Desktop 中使用

将以下配置添加到您的 Claude Desktop 配置文件中

在 Mac 上，配置文件应位于 (~/Library/Application Support/Claude/claude_desktop_config.json)，您也可以通过菜单导航到该文件：设置 > 开发者 > 编辑配置

{
  "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（可选）：排除位置注释

示例提示

提示： "特拉法加广场，伦敦的坐标是什么？"
结果：坐标、时区、当地货币等

提示： "Les Vans, 法国在哪里？它属于哪个省？"
结果：坐标，以及正确答案 Les Vans 位于阿德什省

提示： "Weimar 位于哪个联邦州？"
结果：坐标，以及正确答案 Weimar 位于图林根州

2. geocode-reverse

将坐标转换为地址和有关该位置的信息

参数：

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

示例提示

提示： "38.8976, -77.0365 的地址是什么？"
结果： "1600 Pennsylvania Avenue NW, Washington, DC 20500, United States of America"

提示： "41.38700, 2.16995 的坐标位于哪个省？"
结果： "坐标位于加泰罗尼亚省的巴塞罗那"

3. get-opencage-info

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

参数： 无

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

可用提示

geocoding-assistant

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

错误处理

服务器包括全面的错误处理：

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

环境变量

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

故障排除

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