MCP-Geo

使用 GeoPY 的地理编码 MCP 服务器！

📋 系统要求

• Python 3.6+

📦 依赖项

安装所有必需的依赖项：

# Using uv
uv sync

必需包

• fastmcp: 构建模型上下文协议（MCP）服务器的框架
• geoPy: 用于访问和地理编码/反向地理编码位置的 Python 库。

所有依赖项在 requirements.txt 中指定，以便于安装。

📑 目录

• 系统要求
• 依赖项
• MCP 工具
• 开始使用
• 安装选项
  • Claude Desktop
  • 其他地方
• 安全特性
• 开发文档
• 环境变量

🛠️ MCP 工具

此 MCP 服务器为大型语言模型 (LLMs) 提供以下地理编码工具：

geocode_location

• 接受用户提供的地址或地点名称，并返回最佳匹配的纬度、经度和格式化地址。
• 优雅地处理错误，如果找不到位置或发生错误则返回 None。

reverse_geocode

• 接受纬度和经度并返回最近的地址。
• 适用于查找地图上某点的描述性信息。

geocode_with_details

• 与 geocode_location 类似，但返回额外的数据，如边界框和更详细的地址信息（如果地理编码器支持的话）。

geocode_multiple_locations

• 接受一系列地址字符串，并为每个地址返回地理编码结果列表（纬度/经度/地址）。
• 限速以避免超出地理编码服务配额。

reverse_geocode_multiple_locations

• 接受一系列 [lat, lon] 对，对每个进行反向地理编码。
• 返回包含 lat、lon 和地址的字典列表，对于不成功的查询返回 None，也有限速。

distance_between_addresses

• 计算两个地址或地点名称之间的距离。
• 接受两个地址和一个测量单位（英里/公里）。
• 以指定单位返回距离，如果无法地理编码任一地址，则返回 None。

distance_between_coords

• 计算两组经纬度之间的距离。
• 接受两对纬度和经度以及一个测量单位（公里/英里）。
• 以指定单位返回距离。

🚀 开始使用

克隆仓库：

git clone https://github.com/webcoderz/MCP-Geo.git
cd MCP-Geo

📦 安装选项

您可以在 Claude Desktop 或其他地方安装此 MCP 服务器。选择最适合您需求的选项。

选项 1：为 Claude Desktop 安装

使用 FastMCP 安装：

fastmcp install geo.py --name "MCP Geo"

选项 2：在其他地方安装

要在其他任何地方使用此服务器：

1. 在设置文件中添加以下配置：

{
    "mcp-geo": {
        "command": "uv",
        "args": [
          "--directory",
          "MCP-Geo",
          "run",
          "geo.py"
        ],
        "env": {
        "NOMINATIM_URL": "${NOMINATIM_URL}",
        "SCHEME": "http",
        "GEOCODER_PROVIDER": "nominatim"
        }
    }
}

🔒 安全特性
• 速率限制：每次地理编码调用都受到速率限制（例如，1秒延迟），以避免过度请求违反使用限制。
• 错误处理：捕获 geopy 异常（超时、服务错误）并返回安全的 None 结果，而不是崩溃。

📚 开发文档

如果您想扩展或修改此服务器：
• 查看 geo.py 了解每个工具的实现方式以及 geopy 的集成方式。
• 调整环境变量以切换提供商（Nominatim、ArcGIS、Bing 等）。
• 查看 geopy 的官方文档以获取高级用法，如边界框、语言设置或高级数据提取。

⚙️ 环境变量

使用环境变量配置服务器：

这些可以在您的 shell 中设置，或者在 MCP 设置文件中为您的环境设置。如果需要更多，请编辑 geo.py 并将它们添加到您正在使用的地理编码器中。