Geocoding

地理编码 MCP 服务🗺️

借助 OpenStreetMap Nominatim，将地名和地址转换为坐标（也可反向转换），适用于 Claude Desktop 和任何兼容 MCP 的客户端。支持正向和反向地理编码、地点/兴趣点搜索，以及计算地点之间的距离——全部通过自然语言完成。无需 API 密钥。

npm 包： geocode-mcp  ·  GitHub 仓库： danishashko/geocode-mcp。

🎯 功能一览

• 📍 地理编码 — 地址/地点/地标 → 纬度和经度
• 🔄 反向地理编码 — 坐标 → 易读的地址
• 🔎 地点搜索 — 根据描述查找兴趣点/地点
• 📏 距离 — 计算两个命名地点之间的直线距离

大模型无法独立可靠地完成地理编码——此服务可为 Claude 提供来自 OpenStreetMap 的真实、最新坐标。默认情况下，每个工具都以易读的 Markdown 格式返回结果，也可按需返回结构化 JSON（response_format: "json"）。轻量级（仅依赖 Python 标准库和 mcp），无需 API 密钥。

🚀 快速开始

将以下内容添加到 Claude Desktop 配置中，然后重启 Claude：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "geocode": {
      "command": "npx",
      "args": ["-y", "geocode-mcp"],
      "env": {
        "GEOCODE_USER_AGENT": "your-app-name [email protected]"
      }
    }
  }
}

OpenStreetMap 要求每个客户端都发送包含联系信息的描述性 User-Agent。请将 GEOCODE_USER_AGENT 设置为你自己的姓名/电子邮件（已提供默认值，因此开箱即用）。首次启动时，npx 包装器会创建隔离的 Python 环境并安装依赖项（仅需一次，约一分钟）。你需要 Python 3.10+ 和 Node.js 16+。

更倾向于全局安装？

npm install -g geocode-mcp

{
  "mcpServers": {
    "geocode": {
      "command": "geocode-mcp",
      "env": { "GEOCODE_USER_AGENT": "your-app-name [email protected]" }
    }
  }
}

🔧 可用工具

工具	返回内容	参数
geocode	地址/地点/地标的排序坐标匹配结果	query、limit、country_codes
reverse_geocode	指定纬度/经度处的地址	latitude、longitude
search_places	符合描述的地点/兴趣点及其坐标	query、limit、country_codes
distance_between	两个命名地点之间的直线距离	origin、destination、unit

每个工具也接受 response_format（默认为 "markdown"，也可设为 "json"）。country_codes 是可选的逗号分隔 ISO 3166-1 alpha-2 筛选项（例如 us 或 us,ca）。

💬 提示词示例

连接服务后，直接向 Claude 提问：

• “埃菲尔铁塔的坐标是什么？”
• “纬度 40.7484、经度 -73.9857 处是什么地方？”
• “查找巴黎的书店。”
• “伦敦到爱丁堡有多远？请用英里表示。”
• “对‘1600 Pennsylvania Avenue’进行地理编码——仅限美国。”

🐛 故障排除

“OpenStreetMap 正在限制请求频率” Nominatim 的公共服务每秒允许约 1 个请求。此服务会自行限制请求速率，但如果仍然遇到限制，请稍等片刻。

“未找到位置” 尝试更具体或不同措辞的查询，或者添加 country_codes 筛选条件以消除歧义。

“找不到命令” / “找不到 Python” 确保已安装 Python 3.10+ 和 Node.js 16+，且它们位于 PATH 中。在 macOS/Linux 上，尝试使用 python3。

Claude 中未显示工具

1. 确认配置文件是有效的 JSON（没有尾随逗号）。
2. 完全退出并重新打开 Claude Desktop。

使用其他模型或提供商（LiteLLM、OpenRouter、NVIDIA NIM、本地模型） 此服务不会与模型通信。客户端会将其作为本地进程启动，并通过 stdin/stdout 使用 JSON-RPC 通信，因此更改 ANTHROPIC_BASE_URL 或替换客户端背后的模型不会对其产生影响。如果在进行此类切换后工具不再触发，请检查两点：模型必须支持函数调用；配置为丢弃不支持参数的代理可能会悄悄移除工具定义，且完全不会报错。在怀疑服务本身之前，请先在客户端中运行 /mcp（或运行 claude mcp list），确认服务已连接。

🛠️ 手动安装（替代方式）

如果你更愿意直接运行 Python 文件，而不是通过 npx 运行：

1. 下载服务并安装依赖

pip install mcp

（在 macOS/Linux 上使用 pip3）

2. 将 Claude Desktop 指向该服务

{
  "mcpServers": {
    "geocode": {
      "command": "python3",
      "args": ["/absolute/path/to/geocode_mcp.py"],
      "env": { "GEOCODE_USER_AGENT": "your-app-name [email protected]" }
    }
  }
}

在 Windows 上，使用 "command": "python"，并将路径设为类似 "C:\\path\\to\\geocode_mcp.py" 的形式。

3. 重启 Claude Desktop。

🔒 隐私与使用政策

• 使用 OpenStreetMap 的免费 Nominatim API——公开使用，无需密钥。
• 请求会从你的机器直接发送至 OpenStreetMap。不会存储或代理任何内容。
• 根据 Nominatim 使用政策，服务会发送描述性的 User-Agent，并自行将请求速率限制在每秒约 1 次。请勿将其用于针对公共服务的大批量或高负载工作。
• 数据 © OpenStreetMap 贡献者，依据 ODbL 提供。

📝 注意事项

• distance_between 返回直线（大圆）距离，不是驾车距离或路线距离。
• 结果按相关性/重要性排序；使用 country_codes 缩小有歧义名称的范围（例如“Springfield”）。
• 在水域或偏远地区附近进行反向地理编码时，可能不会返回地址。

📋 更新日志

完整版本历史请参阅 CHANGELOG.md。

📚 资源

• Model Context Protocol
• Nominatim API 文档
• Nominatim 使用政策

⚖️ 法律免责声明

此工具使用 OpenStreetMap Nominatim API，但与 OpenStreetMap Foundation 没有任何关联，也未获其认可。地理编码数据 © OpenStreetMap 贡献者，依据 Open Database License 授权。使用须遵守 Nominatim 使用政策。

👤 作者

Daniel Shashko

• GitHub： @danishashko
• LinkedIn：daniel-shashko
• npm：danielshashko

📄 许可证

MIT © Daniel Shashko