OpenStreetMap (OSM) MCP 服务器

一个增强LLM地理空间服务能力的OpenStreetMap MCP服务器实现。

演示

会面点优化

社区分析

停车搜索

功能特性

本服务器为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 .

2. 启动服务器：

osm-mcp-server

3. 服务器将启动并监听标准输入/输出的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

2. 使用服务器URL初始化客户端：

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

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

# 示例：地址地理编码
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

2. 构建包分发文件：

uv build

将在dist/目录生成源码和wheel分发文件

3. 发布到PyPI：

uv publish

注意：需要通过环境变量或命令行参数设置PyPI凭证

调试方法

由于MCP服务器通过标准输入输出运行，调试具有挑战性。我们强烈推荐使用MCP Inspector获得最佳调试体验。

可通过npm启动MCP Inspector：

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

启动后，检查器将显示可在浏览器访问的调试URL。

API使用示例

以下是Python代码调用关键API端点的快速示例：

import asyncio
from mcp.client import Client

async def main():
    client = Client("http://localhost:8000")
    
    # 地址地理编码
    results = await client.invoke_tool("geocode_address", {"address": "Empire State Building"})
    print(f"找到位置：{results[0]['display_name']}")
    
    # 获取坐标
    lat = float(results[0]['lat'])
    lon = float(results[0]['lon'])
    
    # 查找附近咖啡店
    nearby = await client.invoke_tool(
        "find_nearby_places",
        {
            "latitude": lat,
            "longitude": lon,
            "radius": 500,
            "categories": ["amenity"],
            "limit": 5
        }
    )
    
    # 打印结果
    print(f"找到{nearby['total_count']}个附近地点")
    for category, subcategories in nearby["categories"].items():
        for subcategory, places in subcategories.items():
            print(f"  - {subcategory}: {len(places)}个地点")

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