OpenStreetMap (OSM) MCP 服务器

这是一个 OpenStreetMap MCP 服务器实现，通过基于位置的服务和地理空间数据增强 LLM 的能力。

演示

会面点优化

社区分析

停车搜索

功能

该服务器为 LLM 提供与 OpenStreetMap 数据交互的工具，使基于位置的应用程序能够：

• 将地址和地名转换为坐标
• 将坐标反向编码为地址
• 查找附近的兴趣点
• 获取地点之间的路线方向
• 在指定范围内按类别搜索地点
• 为多人建议最佳会面点
• 探索区域并获取全面的位置信息
• 查找某个位置附近的学校和教育机构
• 分析家与工作地点之间的通勤选项
• 定位带有连接器和功率筛选的电动汽车充电站
• 对房地产进行社区宜居性分析
• 查找带可用性和费用信息的停车场设施

组件

资源

服务器实现了基于位置的资源：

• location://place/{query}: 根据名称或地址获取关于地点的信息
• location://map/{style}/{z}/{x}/{y}: 在指定坐标处获取样式地图瓦片

工具

服务器实现了几个地理空间工具：

• geocode_address: 将文本转换为地理坐标
• reverse_geocode: 将坐标转换为人类可读的地址
• find_nearby_places: 发现某个位置附近的兴趣点
• get_route_directions: 获取地点之间的逐向导航
• search_category: 在一个区域内查找特定类别的地点
• suggest_meeting_point: 为多人找到最佳会面点
• explore_area: 获取有关社区的综合数据
• find_schools_nearby: 定位特定位置附近的教育机构
• analyze_commute: 比较家与工作地点之间的交通选项
• find_ev_charging_stations: 定位带有筛选功能的电动汽车充电基础设施
• analyze_neighborhood: 评估房地产的社区宜居性
• find_parking_facilities: 定位目的地附近的停车选项

使用案例

房地产决策

LLM 可以帮助用户评估潜在的购房社区：

本地测试

运行服务器

要在本地运行服务器，请执行以下步骤：

1. 以开发模式安装包：

pip install -e .

1. 启动服务器：

osm-mcp-server

1. 服务器将启动并在标准输入/输出上监听 MCP 请求。

使用示例客户端进行测试

存储库在 examples/ 目录中包含两个示例客户端：

基本客户端示例

client.py 演示了 OSM MCP 服务器的基本用法：

python examples/client.py

这将：

• 连接到本地运行的服务器
• 获取有关旧金山的信息
• 在该地区搜索餐厅
• 检索带有进度跟踪的全面地图数据

LLM 集成示例

llm_client.py 提供了一个旨在用于 LLM 集成的帮助类：

python examples/llm_client.py

此示例展示了 LLM 如何使用位置助手来：

• 从文本查询中获取位置信息
• 查找附近的兴趣点
• 获取地点之间的路线
• 找到最佳会面点
• 探索周边社区

编写您自己的客户端

要创建您自己的客户端：

1. 导入 MCP 客户端：

from mcp.client import Client

1. 使用您的服务器 URL 初始化客户端：

client = Client("http://localhost:8000")

1. 调用工具或访问资源：

# Example: Geocode an address
results = await client.invoke_tool("geocode_address", {"address": "New York City"})

配置

安装

Claude 桌面版

在 MacOS 上: ~/Library/Application\ Support/Claude/claude_desktop_config.json
在 Windows 上: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "osm-mcp-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/osm-mcp-server",
      "run",
      "osm-mcp-server"
    ]
  }
}

"mcpServers": {
  "osm-mcp-server": {
    "command": "uvx",
    "args": [
      "osm-mcp-server"
    ]
  }
}

开发

构建和发布

为准备包以进行分发：

1. 同步依赖并更新锁定文件：

uv sync

1. 构建包分发：

uv build

这将在 dist/ 目录中创建源代码和 wheel 分发。

1. 发布到 PyPI：

uv publish

注意：您需要通过环境变量或命令标志设置 PyPI 凭据。

调试

由于 MCP 服务器通过 stdio 运行，调试可能会比较困难。为了获得最佳调试体验，我们强烈推荐使用 MCP Inspector。

您可以使用以下命令通过 npm 启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/osm-mcp-server run osm-mcp-server

启动后，Inspector 将显示一个可以在浏览器中访问的 URL 以便开始调试。

示例 API 使用

这里有一个快速示例，展示如何在 Python 代码中使用关键的 API 端点：

import asyncio
from mcp.client import Client

async def main():
    client = Client("http://localhost:8000")
    
    # Geocode an address
    results = await client.invoke_tool("geocode_address", {"address": "Empire State Building"})
    print(f"Found location: {results[0]['display_name']}")
    
    # Get coordinates
    lat = float(results[0]['lat'])
    lon = float(results[0]['lon'])
    
    # Find nearby coffee shops
    nearby = await client.invoke_tool(
        "find_nearby_places",
        {
            "latitude": lat,
            "longitude": lon,
            "radius": 500,
            "categories": ["amenity"],
            "limit": 5
        }
    )
    
    # Print results
    print(f"Found {nearby['total_count']} nearby places")
    for category, subcategories in nearby["categories"].items():
        for subcategory, places in subcategories.items():
            print(f"  - {subcategory}: {len(places)} places")

if __name__ == "__main__":
    asyncio.run(main())