OpenCage-Geocoding MCP 服务

关键词

地理编码坐标转换OpenCage APIJSON-RPC 服务客户端集成

使用说明（Markdown格式）

项目简介

  • 该项目实现了一个 MCP 服务器，作为后端上下文服务，为 MCP 客户端提供地理编码相关的工具、提示模板以及对 OpenCage API 的封装调用。

主要功能点

  • 正向地理编码（geocode-forward）：将地址/地名转换为坐标信息，支持限定语言、国家/地区、范围边界、返回数量等参数。
  • 反向地理编码（geocode-reverse）：将坐标转换为地址信息，支持语言和是否返回注释等选项。
  • 获取 OpenCage API 信息（get-opencage-info）：查询当前的 API 使用情况与速率限制信息。
  • 提供可用工具（工具列表）：按 MCP 规范暴露 geocode-forward、geocode-reverse、get-opencage-info 三个工具及其输入输出描述。
  • 提供提示模板（prompts）：包含 geocoding 助手提示，帮助 MCP 客户端用户更高效地使用地理编码工具。
  • 错误处理：覆盖网络错误、API 错误、无结果等情况的友好反馈。
  • 传输方式：当前实现通过标准输入输出（stdio）进行 MCP 服务器通信，适用于 Claude Desktop 等客户端的集成场景。

安装步骤

  • 确保 Node.js 版本为 20 及以上。
  • 获取 OpenCage API Key（需要注册获取免费/付费密钥）。
  • 安装依赖并构建：
    1. 克隆仓库并进入项目目录
    2. 运行 npm install
    3. 设置环境变量 OPENCAGE_API_KEY（在运行前导出或通过启动脚本传入）
    4. 构建项目：npm run build

服务器配置（MCP 客户端所需信息，为连接 MCP 服务器准备的配置，不属于 MCP 客户端代码） 以下为一个示例配置说明，实际使用时请将路径替换为你本地环境中的绝对路径，并提供你的 API Key。

  • server name: opencage-geocoding
  • command: node
  • args: ["/ABSOLUTE/PATH/TO/opencage-geocoding-mcp/build/index.js"]
  • env: { OPENCAGE_API_KEY: "your_opencage_api_key_here" }

基本使用方法

  • 启动与连接
    1. 在命令行使用上述参数启动 MCP 服务器（确保 OPENCAGE_API_KEY 已设置）。
    2. 使用 MCP 客户端（如 Claude Desktop）配置连接，指定服务器名称、启动命令、参数以及环境变量（如 OpenCage API Key）。
    3. 客户端通过 JSON-RPC 向服务器请求工具（geocode-forward、geocode-reverse、get-opencage-info）并获取结果。
  • 常用流程
    • 列出可用工具：服务器会返回 geocode-forward、geocode-reverse、get-opencage-info 的描述与输入要求。
    • 调用工具：通过工具名和参数发送请求，服务器执行对应的处理逻辑，返回结构化文本信息或错误信息。
    • 获取提示：通过 geocoding-assistant 提示获取帮助信息与可用选项，便于用户提问。

注意事项

  • OpenCage API Key 通过环境变量 OPENCAGE_API_KEY 传入，缺失该变量会导致服务器启动失败。
  • 服务器当前实现使用 stdio 传输，适用于通过命令行或桌面客户端的集成场景。
  • 根据实际部署需要，可将服务改造为其他传输协议（如 SSE、WebSocket），但当前实现仅提供 stdio。

关键词 地理编码, 坐标转换, OpenCage API, JSON-RPC 服务, 客户端集成

分类ID 5

服务器信息

访问项目