MCP-Geo

MCP-Geo

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

📋 系统要求

• Python 3.6+

📦 依赖项

安装所有必需的依赖项：

# Using uv
uv sync

必需的软件包

• fastmcp：用于构建 Model Context Protocol 服务的框架
• geoPy：用于访问地理位置并进行正向和反向地理编码的 Python 库。

所有依赖项都列在 requirements.txt 中，便于安装。

📑 目录

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

🛠️ MCP 工具

此 MCP 服务向大语言模型（LLM）提供以下地理编码工具：

geocode_location

• 接收用户提供的地址或地点名称，并返回最佳匹配项的纬度、经度和格式化地址。

• 妥善处理错误；如果未找到地点或发生错误，则返回 None。

reverse_geocode

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

geocode_with_details

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

geocode_multiple_locations

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

reverse_geocode_multiple_locations

• 接收 [lat, lon] 坐标对列表，并对每一对坐标执行反向地理编码。
• 返回字典列表，其中包含纬度、经度和地址；查询失败时地址为 None。此操作同样受速率限制。

distance_between_addresses

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

distance_between_coords

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

🚀 开始使用

克隆此仓库：

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 官方文档，了解边界框、语言设置或高级数据提取等高级用法。

⚙️ 环境变量

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

变量	描述	默认值
GEOCODER_PROVIDER (optional)	"nominatim"、"arcgis" 或 "bing"	nominatim
NOMINATIM_URL (optional)	Nominatim 的域名	nominatim.openstreetmap.org
SCHEME (optional)	http/https	http
ARC_USERNAME (optional for ArcGIS)	ArcGIS 用户名	None
ARC_PASSWORD (optional for ArcGIS)	ArcGIS 密码	None
BING_API_KEY (required for Bing)	你的 Bing Maps 密钥。	None

可以在 shell 中或环境的 MCP 设置文件中设置这些变量。如果还需要其他变量，只需编辑 geo.py，并将它们添加到你使用的地理编码器中。