JinDaGe - opencage-geocoding-mcp MCP Details

article

README

🚀 OpenCage地理编码MCP服务器

OpenCage地理编码MCP服务器是一个运用 OpenCage地理编码API 提供地理编码功能的MCP（模型上下文协议）服务器。该服务器可让你在地址和地理坐标之间进行转换。

请注意：此处展示的示例基于与 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桌面版一起工作（见下文）。

如果你想开发MCP并计划从命令行查询MCP，还需要： 3. 将你的OpenCage地理编码API密钥设置为环境变量：

export OPENCAGE_API_KEY="your_opencage_geocoding_api_key_here"

构建项目：

npm run build

💻 使用示例

在Claude桌面版中使用

将以下配置添加到你的Claude桌面版配置文件中。

在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（可选）：边界框（最小经度,最小纬度,最大经度,最大纬度）。
language（可选）：结果的语言（例如，'en'、'de'、'fr'）。
limit（可选）：最大结果数（1 - 100，默认10）。
no_annotations（可选）：排除位置注释。

示例提示：

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

提示："法国的莱斯旺斯在哪里？它在哪个省？"
结果：坐标，并正确回答莱斯旺斯在阿尔代什省。

提示："魏玛在哪个联邦州？"
结果：坐标，并正确回答魏玛在图林根州。

2. geocode-reverse

将坐标转换为地址以及该位置的相关信息。参数：

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

示例提示：

提示："38.8976, -77.0365的地址是什么？"
结果："美国华盛顿特区宾夕法尼亚大道1600号，邮编20500"

提示："坐标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公共状态页面。

OpenCage GmbH是谁？

我们基于开放数据运行全球地理编码API 和地理搜索服务。了解更多关于我们的信息。

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

opencage-geocoding-mcp