OpenStreetMap MCP Server

OpenStreetMap MCP 服务

概述

这是一个使用 Go 编写的 OpenStreetMap MCP 服务。它实现了 Model Context Protocol，以便大模型与地理空间数据交互。

我们专注于精确性、性能、可维护性，以及与 MCP 桌面客户端轻松集成。

功能

该服务为大模型提供了与 OpenStreetMap 数据交互的工具，包括：

• 将地址和地名地理编码为坐标
• 将坐标反向地理编码为地址
• 查找附近的兴趣点
• 计算路线并获取地点间的路线指引
• 在边界框内按类别搜索地点
• 为多人推荐最佳会面地点
• 探索区域并获取全面的位置信息
• 查找地点附近的电动汽车充电站
• 查找路线沿途的电动汽车充电站
• 分析住宅与工作地点之间的通勤方案
• 进行社区宜居性分析
• 查找地点附近的学校
• 查找停车设施

已实现的工具

工具名称	描述	示例参数
bbox_from_points	创建一个包含所有给定地理坐标的边界框	{"points": [{"latitude": 37.7749, "longitude": -122.4194}, {"latitude": 37.8043, "longitude": -122.2711}]}
centroid_points	计算一组坐标的地理质心（平均中心）	{"points": [{"latitude": 37.7749, "longitude": -122.4194}, {"latitude": 37.8043, "longitude": -122.2711}]}
enrich_emissions	为路线选项补充 CO2 排放量、卡路里消耗和费用估算	{"options": [{"mode": "car", "distance": 5000}, {"mode": "bike", "distance": 4500}]}
filter_tags	根据指定标签筛选 OSM 元素	{"elements": [...], "tags": {"amenity": ["restaurant", "cafe"]}}
geocode_address	将地址或地点名称转换为地理坐标	{"address": "1600 Pennsylvania Ave, Washington DC"}
geo_distance	计算两个地理坐标之间的距离	{"from": {"latitude": 37.7749, "longitude": -122.4194}, "to": {"latitude": 37.8043, "longitude": -122.2711}}
get_map_image	获取并显示 OpenStreetMap 图像以供分析	{"latitude": 37.7749, "longitude": -122.4194, "zoom": 14}
osm_query_bbox	使用标签筛选条件查询边界框内的 OpenStreetMap 数据	{"bbox": {"minLat": 37.77, "minLon": -122.42, "maxLat": 37.78, "maxLon": -122.41}, "tags": {"amenity": "restaurant"}}
polyline_decode	将编码后的折线字符串解码为一系列地理坐标	{"polyline": "a~l~FfynpOnlB_pDhgEhjD"}
polyline_encode	将一系列地理坐标编码为折线字符串	{"points": [{"latitude": 37.7749, "longitude": -122.4194}, {"latitude": 37.8043, "longitude": -122.2711}]}
reverse_geocode	将地理坐标转换为易读地址	{"latitude": 38.8977, "longitude": -77.0365}
route_fetch	使用 OSRM 路线服务获取两点之间的路线	{"start": {"latitude": 37.7749, "longitude": -122.4194}, "end": {"latitude": 37.8043, "longitude": -122.2711}, "mode": "car"}
route_sample	按指定间隔对路线上的点进行采样	{"polyline": "a~l~FfynpOnlB_pDhgEhjD", "interval": 100}
sort_by_distance	按 OSM 元素与参考点之间的距离对元素排序	{"elements": [...], "ref": {"latitude": 37.7749, "longitude": -122.4194}}
find_nearby_places	查找特定地点附近的兴趣点	{"latitude": 37.7749, "longitude": -122.4194, "radius": 1000, "category": "restaurant", "limit": 5}
get_route_directions	获取地点之间路线的详细逐向导航指引	{"start_lat": 37.7749, "start_lon": -122.4194, "end_lat": 37.8043, "end_lon": -122.2711, "mode": "car"}
suggest_meeting_point	为多人推荐最佳会面地点	{"locations": [{"latitude": 37.7749, "longitude": -122.4194}, {"latitude": 37.8043, "longitude": -122.2711}], "category": "cafe", "limit": 3}
explore_area	探索一个区域并获取其综合信息	{"latitude": 37.7749, "longitude": -122.4194, "radius": 1000}
find_charging_stations	查找地点附近的电动汽车充电站	{"latitude": 37.7749, "longitude": -122.4194, "radius": 5000, "limit": 10}
analyze_commute	分析住所与工作地点之间的出行方式	{"home_latitude": 37.7749, "home_longitude": -122.4194, "work_latitude": 37.8043, "work_longitude": -122.2711, "transport_modes": ["car", "cycling", "walking"]}
analyze_neighborhood	评估社区宜居性，为房地产和搬迁决策提供参考	{"latitude": 37.7749, "longitude": -122.4194, "radius": 1000, "include_price_data": true}
find_schools_nearby	查找特定地点附近的教育机构	{"latitude": 37.7749, "longitude": -122.4194, "radius": 2000, "school_type": "elementary", "limit": 5}
find_parking_facilities	查找特定地点附近的停车设施	{"latitude": 37.7749, "longitude": -122.4194, "radius": 1000, "type": "surface", "include_private": false, "limit": 5}

新增地理与路线工具

v0.1.1 版本增强了地理与路线功能：

地理工具

• 边界框生成：创建可涵盖多个点的地理边界框。
• 质心计算：查找一组地理坐标的平均中心点。
• 距离计算：使用 Haversine 公式计算地理点之间的精确距离。
• OSM 元素筛选：按标签和距离筛选并排序 OpenStreetMap 元素。

折线工具

• 折线编码/解码：在地理坐标与 Google 的 Polyline5 格式之间转换。
• 路线采样：按特定间隔沿路线采样点，以便进行详细分析。

路线工具

• 路线获取：使用 OSRM 路线服务获取点与点之间的路线。
• 排放数据增强：为路线选项补充预估的 CO2 排放量、卡路里消耗和成本数据。

这些工具为大模型提供了基础地理能力，可用于构建复杂的位置应用。

可组合的工具设计

我们的许多 MCP 工具都设计为可组合的基础构件，能够支持开发期间未曾预见的新工作流。我们还提供组合工具，以高效执行常见的复杂操作。

组合原则

• 统一接口：所有工具都采用一致的参数命名（例如 minLat、maxLon）和数据结构
• 单一职责：每个工具只负责一件事，并将其做好
• 输出/输入兼容性：一个工具的输出可直接用作另一个工具的输入
• 功能独立：工具运行时不会产生副作用，也不依赖隐藏的依赖项
• 精确的错误消息：出现问题时，详细反馈会准确指出问题所在

工作流示例

1. 查找路径沿线的兴趣点：

   bbox_from_points → osm_query_bbox → filter_tags → sort_by_distance
   

2. 查找最佳会面地点：

   centroid_points → find_nearby_places → filter_tags
   

3. 分析路线特征：

   route_fetch → polyline_decode → route_sample → filter_tags
   

这种组合式方法让大模型能够创造出超越任何单个工具能力的新兴功能。例如，大模型可以组合适当的基础工具，轻松创建“显示我路线沿线最近的五家无障碍咖啡馆，且营业时间超过 22:00”的查询，而无需自定义服务端端点。

可视化地图功能

MCP 服务通过一个工具提供可视化地图功能：

1. get_map_image - 以 SVG 格式返回地图图像，便于改进可视化和分析

用于分析的地图图像

get_map_image 工具提供地图功能，可同时返回地图的可视化表示和详细元数据。这种方式具有以下优势：

• 视觉显示：返回实际地图瓦片图像，并在对话中内嵌显示
• 直接可视化：让 Claude 能够直观分析地图特征和地理信息
• 全面的元数据：包含精确坐标、边界和比例尺信息
• 丰富的上下文：提供文本说明，并附带可进一步探索的 OpenStreetMap 直接链接

该工具同时返回地图瓦片图像和结构化文本说明，其中包含位置坐标、用于在线查看地图的直接链接，以及有关地图区域的详细元数据，因此适用于视觉分析和全面了解位置。

使用示例

要获取旧金山在缩放级别 14 下的地图图像：

{
  "name": "get_map_image",
  "arguments": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "zoom": 14
  }
}

该工具的响应包括：

• 在对话中内嵌显示的地图瓦片图像
• 带有 OpenStreetMap 直接链接的位置文本说明
• 地图的精确坐标信息
• 可视区域的地理边界
• 比例尺信息（每像素对应的米数）

改进的地理编码工具

地理编码工具经过增强，能够提供更可靠的结果并改进错误处理：

主要改进

• 智能地址预处理：自动清理输入内容，提高成功率
• 详细错误报告：返回包含错误代码和实用建议的结构化错误响应
• 更完善的诊断：提供详细日志，便于追踪地理编码问题
• 改进的格式指南：文档提供了具体示例，说明哪些格式效果良好

地理编码最佳实践

使用地理编码工具时，如需获得最佳结果，请遵循以下建议：

1. 简化复杂查询：

   • 不佳：“Golden Temple (Harmandir Sahib) in Amritsar”
   • 良好：“Golden Temple Amritsar India”

2. 补充地理上下文：

   • 不佳：“Eiffel Tower”
   • 良好：“Eiffel Tower, Paris, France”

3. 阅读错误建议：

   • 增强后的错误响应会提供具体建议，帮助修正失败的查询

请参阅 地理编码工具指南 获取完整文档，并参阅 地理编码 AI 提示词，了解如何引导 AI 系统有效使用这些工具。

代码架构与设计

代码遵循软件工程最佳实践：

1. 高内聚、低耦合——每个包都有明确且专注的职责
2. 关注点分离——工具、服务端逻辑和实用工具清晰分离
3. DRY（不要重复自己）——将通用实用工具提取到 pkg/osm 包中
4. 安全优先——HTTP 客户端经过适当配置，设有超时和连接数限制
5. 类 UNIX 的可组合性——小型、专注的工具可以灵活组合，发挥强大作用
6. 结构化日志记录——所有日志均通过 slog 记录，并采用一致的级别和格式：
   • Debug：开发细节、详细信息或诊断消息
   • Info：常规运行消息
   • Warn：意外情况，但不一定会中断执行
   • Error：严重问题、潜在故障或实际故障
7. SOLID 原则——尤其是单一职责和接口隔离原则
8. 注册表模式——在中央注册表中定义所有工具，以提高可维护性
9. Google Polyline5 格式——使用 Google 的 Polyline5 格式进行标准化的折线编码和解码
10. 精确的地理空间计算——采用适当容差进行准确的 Haversine 距离计算
11. 上下文感知操作——所有操作都能妥善处理上下文取消和超时

使用方法

安装

安装 OpenStreetMap MCP 服务：

选项 1：下载预构建二进制文件

最简单的入门方式是从我们的发布页面下载最新版本。选择适用于你的操作系统和架构的二进制文件。

选项 2：从源代码构建

如果你希望从源代码构建：

### Requirements

- Go 1.24 or higher
- OpenStreetMap API access (no API key required, but rate limits apply)

### Building the server

```bash
go build -o osmmcp ./cmd/osmmcp

运行服务

./osmmcp

该服务支持多个命令行标志：

# Show version information
./osmmcp --version
# The version may differ if built with custom -ldflags

# Enable debug logging
./osmmcp --debug

# Generate a Claude Desktop Client configuration file
./osmmcp --generate-config /path/to/config.json

# Customize rate limits (requests per second and burst)
# Defaults: Nominatim=1 rps/burst 1, Overpass=2 per min/burst 2, OSRM=100 per min/burst 5
./osmmcp --nominatim-rps 1.0 --nominatim-burst 1
./osmmcp --overpass-rps 0.033 --overpass-burst 2
./osmmcp --osrm-rps 1.67 --osrm-burst 5

# Set custom User-Agent string
./osmmcp --user-agent "MyApp/1.0"

日志配置

该服务通过 slog 使用结构化日志，并采用以下配置：

• Debug 级别：通过 --debug 标志启用
• 默认级别：Info
• 格式：采用键值对的文本格式
• 输出：标准错误（stderr）

日志输出示例：

2024-03-14T10:15:30.123Z INFO starting OpenStreetMap MCP server version=0.1.0 log_level=info user_agent=osm-mcp-server/0.1.0
2024-03-14T10:15:30.124Z DEBUG rate limiter initialized service=nominatim rps=1.0 burst=1

该服务将启动，并在标准输入/输出上监听 MCP 请求。你可以将其与任何兼容 MCP 的客户端或大模型集成搭配使用。

与 Claude Desktop Client 配合使用

此 MCP 服务专为与 Claude Desktop Client 配合使用而设计。按照以下步骤即可轻松完成设置：

1. 构建服务：

   go build -o osmmcp ./cmd/osmmcp
   

2. 生成或更新 Claude Desktop Client 配置：

   ./osmmcp --generate-config ~/Library/Application\ Support/Anthropic/Claude/config.json
   

   这将在 Claude Desktop Client 的 mcpServers 配置中添加一个 OSM 条目。配置系统会智能地：

   • 如果文件不存在，则创建该文件
   • 更新配置时保留现有工具
   • 使用绝对路径，确保 Claude 能找到可执行文件
   • 验证 JSON 输出，避免配置损坏

3. 重启 Claude Desktop Client 以加载更新后的配置。

4. 现在，你可以在与 Claude 的对话中使用 OpenStreetMap MCP 工具。

配置文件将类似于：

{
  "mcpServers": {
    "OSM": {
      "command": "/path/to/osmmcp",
      "args": []
    },
  }
}

API 依赖项

此服务依赖以下外部 API：

• Nominatim - 用于地理编码操作
• Overpass API - 用于查询 OpenStreetMap 数据
• OSRM - 用于路线计算

这些都是开放的公共 API，因此无需 API 密钥，但此服务会遵循使用政策，包括正确标识用户代理和限制请求速率。

开发

项目结构

• cmd/osmmcp - 主应用程序入口点
• pkg/server - MCP 服务实现
• pkg/tools - OpenStreetMap 工具实现和工具注册表（25 个工具）
• pkg/osm - OpenStreetMap API 客户端、速率限制、折线编码和实用程序
• pkg/geo - 地理类型、边界框和 Haversine 距离计算
• pkg/core - 核心实用程序，包括 HTTP 重试逻辑、验证、错误处理、Overpass 查询构建器和 OSRM 服务客户端
• pkg/cache - 用于缓存 API 响应的基于 TTL 的缓存层（默认 5 分钟）
• pkg/monitoring - Prometheus 指标、健康检查、连接监控和可观测性
• pkg/tracing - 用于分布式追踪和调试的 OpenTelemetry 追踪支持
• pkg/testutil - 测试实用程序和辅助函数
• pkg/version - 构建元数据和版本信息

添加新工具

添加新工具的步骤：

1. 在 pkg/tools 中的新文件或现有文件里实现工具函数
2. 将工具定义添加到 pkg/tools/registry.go 中的注册表

基于注册表的设计，无需修改多个文件即可轻松添加新工具。所有工具定义都集中在一处，使代码库更易于维护。

测试

运行测试：

go test ./...

测试套件包括：

• 折线编码/解码单元测试
• 服务集成测试
• 地理计算测试
• 日志实用程序测试

致谢

此实现基于以下两个优秀项目：

• jagan-shanmugam/open-streetmap-mcp - 原始 Python 实现
• MCPLink OSM MCP Server - 具有更多功能的 MCPLink 版本

项目历史

最初由 @pdfinn 创建。
所有核心功能和初始版本均在组织转让前开发完成。

文档

• GoDoc - 完整的 API 文档
• 地理编码工具指南 - 地理编码功能和最佳实践的详细指南
• 地理编码的 AI 提示词 - 用于将 AI 与地理编码工具集成的系统提示词和示例

许可证

MIT 许可证