AI导哈

位置信息查询服务

一个基于OpenStreetMap Nominatim API的MCP服务器示例，提供地址/地点名称查询功能，返回显示名称、坐标和地点类型等基本信息。

  • by bhuppal
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 bhuppal/mcp_server_property

使用说明

MCP服务器：Nominatim属性信息示例

此存储库包含一个最小的MCP（模型连接器协议）服务器，用于演示如何使用OpenStreetMap Nominatim API向语言模型暴露属性/位置查找功能。此示例有意设计得小巧且本地化，以便轻松使用Claude桌面应用程序（或其他MCP客户端）运行。

概述

MCP服务器通过将语言模型与数据源和服务连接起来，扩展了语言模型的功能。它们提供了三种主要的原语（或基本功能）：

  • 资源（客户端控制）：在请求时暴露数据以用作上下文。用于被动数据访问。
  • 工具（模型控制）：提供模型可调用的可执行功能，用于获取或转换数据。
  • 提示（用户控制）：向用户提供可重用的提示和工作流。

这个示例专注于一个单一工具， get_property_info，它使用Nominatim API查找地址/地名，并返回基本位置信息（显示名称、坐标和地点类型）。

为什么选择Nominatim？

  • 非商业用途可免费使用（需遵守Nominatim使用政策）。
  • 简单查询无需API密钥。
  • 返回关于地点和坐标的结构化、机器友好的JSON数据。

重要提示：Nominatim 实施速率限制，并要求提供描述性的 User-Agent 请求头。请参阅下面的使用说明。

内容

  • mcp-server-property.py — 本示例中使用的MCP服务器入口点。
  • pyproject.toml — 项目元数据和依赖项。
  • README.md — 这个文件。

要求

  • 一个 Claude.ai 账户以及 Claude 桌面应用程序（用于 MCP 客户端测试），或任何具备 MCP 功能的客户端。
  • 一个代码编辑器（推荐使用VS Code）。
  • 一个Python 3.10+的环境。
  • uv （可选）或者使用标准的虚拟环境（venv）进行环境管理。

快速设置

  1. 在您的编辑器中打开项目文件夹。

  2. 创建并激活一个虚拟环境（或使用 uv （如果你更喜欢）：

python -m venv .venv
source .venv/bin/activate
  1. 将运行时依赖项安装到当前活动环境中：
pip install "mcp[cli]" httpx

注释：

  • 如果你使用 uv （在一些MCP材料中提到的基于Rust的Python环境管理器），你也可以运行 uv venv 和 uv add "mcp[cli]" httpx。

服务器

示例服务器初始化了一个 FastMCP 实例化并暴露一个单一工具：

  • get_property_info(address: str) -> str — 举头看 address 使用Nominatim，并返回一个简短、易于人类阅读的字符串，其中包含显示名称、地点类型、纬度和经度。

关键的实施细节在于 mcp-server-property.py：

  • 用途 httpx.AsyncClient 执行HTTP请求。
  • 发送一个 User-Agent 标题（对于遵守Nominatim政策至关重要）。
  • 将结果限制为最佳匹配项（limit=1）。

运行MCP服务器

以开发者模式启动服务器（如果可用，这还将运行MCP检查器）：

mcp dev mcp-server-property.py

或者直接运行服务器以使用stdio传输（适用于通过stdio连接的MCP客户端）：

python mcp-server-property.py

当运行时，服务器注册了 get_property_info 工具。在MCP检查器或您的MCP客户端中，使用地址字符串调用该工具，例如：

示例输入：

221B Baker Street, London

预期输出（工具返回的用户友好字符串）：

🏠 Property Info:
- Address: 221B, Baker Street, Marylebone, London, Greater London, England, NW1 6XE, United Kingdom
- Type: house
- Latitude: 51.523771
- Longitude: -0.158538

注：确切的显示名称和地点类型取决于Nominatim的数据集，可能会有所不同。

使用说明和最佳实践

  • 请遵守Nominatim的使用政策：不要用快速的自动化请求淹没API。如果您计划频繁调用API，请考虑添加缓存或限制请求速率。
  • 提供描述性内容 User-Agent 识别您的应用程序（示例设置 mcp-property-demo/1.0）。
  • 对于高流量或商业用途，建议考虑使用付费的地理编码服务提供商或托管的Nominatim实例。

扩展服务器

  • 添加一个 get_location 一个工具，用于返回原始的Nominatim JSON数据，以便模型进行后续处理。
  • 添加缓存（内存缓存或持久缓存）以避免对同一地址进行重复查找。
  • 添加资源以向客户端暴露最近的查询结果或聚合数据。

故障排除

  • 如果MCP服务器没有按预期运行，请检查运行服务器的终端以查看堆栈跟踪。
  • 确保您的虚拟环境已激活，并且在该环境中已安装所有依赖项。

许可证

这个项目是一个小型示例，仅供学习之用。请随意使用和修改。

相关 MCP