BikeScout MCP 服务器

BikeScout 是一个专为自行车和山地自行车爱好者设计的专业 MCP 服务器。它通过结合真实地图数据与高级路线分析，提供智能化的骑行路线推荐。

核心功能

• 真实路线发现：通过 OpenStreetMap（使用 Overpass API）获取真实的路线名称和路面类型。

• 技术指标：计算精确的公里数和总爬升高度。

• 难度与技术分级：将路线评估为初级、中级或专家级，并分析 OSM 道路类型（1-5 级），以区分平整的碎石路和崎岖的山地车路径。

• 动态路线与路面分析：生成建议的环形路线，并提供详细的路面类型百分比分解（沥青、碎石、泥土等）。

• 自行车配置兼容性：首创功能，可检查路线是否适合您的特定自行车（公路车、碎石车或山地车）及轮胎宽度，并提供即时安全警告。

• 预测性泥泞风险分析：专为越野骑行者设计的模型，通过交叉比对 72 小时历史降水量与土壤地质（如粘土与沙土）来预测路线的可骑行性。

• 智能兴趣点 (POI) 搜寻（补给站查找器）：自动定位路线半径 2 公里内的骑行专用设施，如饮水点、自行车维修站和山间避难所。

• 智能安全与天气预报：将位置数据与实时天气交叉比对，确保您不会遭遇风暴。

• 专业骑行装备建议：根据温度、风力和降雨阈值提供具体的服装和装备技术建议。

• 无缝位置搜索：无需 GPS 坐标。通过集成的 Nominatim 地理编码，使用自然语言（例如：“在 Albano Laziale 找一条骑行路线”）即可搜索。

• 即时地图预览：自动生成路线的静态地图 (.png)，以便在聊天界面中直接查看路线。

• 本地专家知识：针对世界级目的地（如 多洛米蒂山脉 (UNESCO)、摩押 (美国) 和 Castelli Romani）提供专门的区域提示。

• 专业爬坡分级：根据长度和平均坡度，使用专业骑行标准自动识别并命名特定的爬坡路段（从 4 级 到 HC 超级爬坡）。

为什么选择 BikeScout？（对比通用地图）

虽然 Google 地图或标准导航工具在城市通勤方面表现出色，但在地形变得复杂时它们往往力不从心。BikeScout 弥补了简单的“地图线条”与专业骑行技术现实之间的差距，将您的 AI 变成一位专业的本地向导。

真实的爬升数据（渐进式过滤）

原始卫星数据 (SRTM) 常带有“噪声”，由于读数突变，在山区往往会将总垂直爬升高度高估多达 40%。

• 通用地图：显示“锯齿状”的爬升剖面，夸大了骑行难度并使图表难以阅读。

• BikeScout：使用渐进式爬升过滤器。我们的算法能够识别并平滑卫星传感器的误差，返回与真实气压传感器（Garmin/Wahoo）相符的总爬升值。

超越“铺装”与“未铺装”（S-Scale 分级）

对于标准导航仪来说，路就是路。但对于骑行者而言，压实的碎石路与松散的岩石路面之间，就是乐趣与危险的区别。

• 通用地图：不加区分地将所有非沥青路面标记为“未铺装”。

• BikeScout：解析深层的 OpenStreetMap 元数据以提取 MTB-Scale (S0-S5) 和 SAC-Scale。它会警告您是否会遇到 S0 级（简单）或 S3 级（带有岩石和台阶的技术路段），让您判断自己的装备是否合适。

超越传统 POI

通用地图通常优先显示赞助商结果或餐厅。BikeScout 会深入探测 OpenStreetMap 标签，如 amenity=drinking_water 和 shop=bicycle。这些点通常由骑行社区验证，确保您在山口找到的是真正可用的饮水点，而不是一家已倒闭的超市。

历史天气数据

标准预报只会告诉您是否会下雨。BikeScout 会分析已经发生的情况。由于粘土含量高的土壤在暴雨后可能数天无法骑行，而沙质土壤几小时内即可变干，该工具提供了越野决策所需的具体背景信息。

针对不同骑行类型的智能分析

骑行难度与您的装备有关。500 米的爬升在 7 公斤的公路车上与在 16 公斤、配备 2.4 英寸粗齿胎的 Enduro 车上感觉完全不同。

• 通用地图：基于通用平均值提供“标准”旅行时间和难度。

• BikeScout：具备动态努力引擎。它根据您的自行车类型（公路、碎石、山地、Enduro）和轮胎配置，专门计算难度和爬坡分级（从 4 级到 HC 超级爬坡）。

原生 AI 编排 (MCP)

BikeScout 不仅仅是一个独立的脚本，它是下一代大语言模型的原生扩展。

• 通用地图：需要用户手动搜索、截图和视觉解读。

• BikeScout：是一个 模型上下文协议 (MCP) 服务器。它允许 Claude、Cursor 或其他 LLM 像本地向导一样进行“推理”，在单一对话流中自动交叉比对天气、土壤类型和技术配置。

功能对比一览

新闻、博客与在线演示

获取最新的战术骑行情报、任务报告和 MCP 生态系统新闻。

• 官方网站：https://hifly81.github.io/bikescout

• 战术博客：https://hifly81.github.io/bikescout/site/blog.html

先决条件

• Python 3.10+

• OpenRouteService API Key：在 openrouteservice.org 获取免费密钥。

• MCP 客户端：例如 Claude Desktop。

安装

BikeScout 可在 PyPI 上获取。您可以使用 pip 或 uv 直接安装。

我们建议在虚拟环境中安装 BikeScout：

python -m venv venv
source venv/bin/activate 
pip install bikescout

配置您的 OpenRouteService API 密钥：

export ORS_API_KEY=YOUR_OPENROUTE_SERVICE_API_KEY

Claude Desktop 配置

• 将仓库克隆到本地文件夹：

  git clone git@github.com:hifly81/bikescout.git <your_local_folder_path>

• 从本地文件夹创建 Python 虚拟环境：

  python3 -m venv venv
  source venv/bin/activate
  pip install bikescout

将服务器添加到您的 claude_desktop_config.json：

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

您必须将 JSON 配置中的占位符替换为您 Python 脚本文件的本地绝对路径。 PATH/TO/YOUR/BIKESCOUT_FOLDER/src/bikescout/mcp_server.py

示例：

• Linux/macOS: /home/username/bikescout/src/bikescout/mcp_server.py

• Windows: C:/Users/Username/Documents/bikescout/src/bikescout/mcp_server.py

{
  "mcpServers": {
    "bikescout": {
      "command": "PATH/TO/YOUR/BIKESCOUT_FOLDER/venv/bin/python3",
       "args": [
          "-u",
          "-m",
          "bikescout.mcp_server"
       ],
      "env": {
        "PYTHONPATH": "PATH/TO/YOUR/BIKESCOUT_FOLDER/src", 
        "ORS_API_KEY": "YOUR_OPENROUTE_SERVICE_API_KEY"
      }
    }
  }
}

在 VS Code 中使用 BikeScout

如果您在编码时想要测试 BikeScout 服务器，实际上不需要 Claude Desktop 应用。您可以将 VS Code 与 Cline（原 Claude Dev）或 Continue 扩展结合使用。

• 安装扩展：

  前往 VS Code 市场并安装 Cline 扩展（或 Continue）。这些扩展充当 AI 与本地机器之间的“桥梁”。

• 将仓库克隆到本地文件夹：

git clone git@github.com:hifly81/bikescout.git <your_local_folder_path>

• 从本地文件夹创建 Python 虚拟环境：

  python3 -m venv venv
  source venv/bin/activate
  pip install bikescout

• 打开 MCP 设置：

  在扩展设置中（通常是齿轮图标或扩展侧面板中的特定“MCP”选项卡），查找标题为“Configure MCP Servers”的部分。

• 添加 JSON 配置：

  将以下 JSON 配置粘贴到设置文件中（确保更新为您实际目录的路径）：

{
   "mcpServers": {
      "bikescout": {
         "command": "PATH/TO/YOUR/BIKESCOUT_FOLDER/venv/bin/python3",
         "args": [
            "-u",
            "-m",
            "bikescout.mcp_server"
         ],
         "env": {
            "PYTHONPATH": "PATH/TO/YOUR/BIKESCOUT_FOLDER/src",
            "ORS_API_KEY": "YOUR_OPENROUTE_SERVICE_API_KEY"
         }
      }
   }
}

• 开始探索 保存后，您就可以直接在 VS Code 中与 AI 聊天。它会自动将 BikeScout 检测为“工具”。您可以询问：“帮我找一条从我当前坐标出发的 30 公里风景优美的山地车路线。” AI 将执行 Python 脚本，从 OpenStreetMap 和 OpenRouteService 获取数据，并将结果直接呈现在您的聊天窗口中。

调试与测试

您可以使用 MCP Inspector 测试 BikeScout，这是一个用于测试 MCP 服务器的基于 Web 的工具。

使用 Inspector

要启动 inspector 并手动与工具交互，请从根目录运行以下命令：

export ORS_API_KEY=YOUR_OPENROUTE_SERVICE_API_KEY
PYTHONPATH=./src npx @modelcontextprotocol/inspector ./venv/bin/python3 -m bikescout.mcp_server

检查内容：

• 列出工具：确保所有工具（geocode_location, trail_scout 等）均可见。

• 运行工具：通过传入城市名称（例如“Rome”）来测试 geocode_location 工具，以验证 Nominatim 集成。

查询示例

您可以向 BikeScout 提出复杂的多步骤请求。它结合了实时数据与专业骑行情报，提供专家级的回答。

高级规划（多工具）

• “我目前在 Monte Cavo，骑的是 碎石车（40mm 轮胎）。帮我规划一条 25 公里的环线。检查地形是否与我的车兼容，核实下午的降雨概率，并推荐一个终点处的‘Fraschetta’餐厅。使用 Castelli Romani 指南。”

• “我明天想在 摩押 (Moab) 骑行。我有一辆 硬尾山地车。帮我找一条 20 公里 且不太技术的路线（避开 4/5 级路段），检查高温预报，并给我一份沙漠安全检查清单。”

自行车配置与路面情报

• “检查这条 [LAT, LON] 的 15 公里环线。我骑的是 配备 25mm 轮胎的公路车。它兼容吗？告诉我碎石路与沥青路的精确比例。”

• “我计划在日本 京都 骑行。找一条 30 公里 的环线，要求至少 70% 是碎石路，但前提是未来 4 小时内的降雨概率低于 10%。”

本地专业知识

• “使用 Dolomiti 本地指南 规划一条从 Cortina 出发的公路骑行路线。我需要至少 800 米的爬升。另外，推荐高海拔下坡的正确胎压，以及一个可以吃苹果卷的山间小屋。”

• “在 加拿大温哥华 附近有命名的路线吗？分析路面类型，并告诉我它们是否适合 E-MTB 的初学者。”

快速技术检查

• “给我一份 安全检查清单，并计算一名 90 公斤骑手 在泥泞路面上使用 2.3 英寸真空胎 的 胎压。”

• “在 台中 进行 10 公里骑行 的地形构成是什么？我需要知道是否会遇到任何‘5 级’技术路段。”

响应示例

以下是 BikeScout 可以提供的详细信息示例：

我在 意大利弗拉斯卡蒂 (Frascati) 附近找到了一条山地车环线。详情如下：

📊 路线详情

• 📍 距离： 11.26 公里

• ⛰️ 总爬升： 856 米

• 🏷️ 难度： 专家级（挑战性距离或非常陡峭的爬坡）

• 🛤️ 包含路线： Viale Moderno, Via dei Sepolcri

• 🔗 地图： 在 Google 地图上查看

• 🔗 路线地图图片： mtb_route_map.png

关键路线特征

• 技术地形：带有技术路段的山地车路径

• 爬升剖面：从 Rocca di Papa (703m) 到 Albano Laziale (542m) 的显著下坡

• 路面类型：碎石、泥土和森林小径的混合

• 风景：阿尔班山和罗马乡村的美丽景色

装备检查清单

• 自行车：建议使用全避震山地车以应对技术地形

• 头盔：强制性安全装备

• 补水：至少 2 升水

• 营养：针对 15 公里距离的能量棒/能量胶

• 维修工具包：备用内胎、打气筒、多功能工具

• 服装：针对海拔变化的分层穿衣

• 导航：GPS 设备或加载了 GPX 文件的智能手机

安全提示

• 这是一条专家级路线，包含技术路段

• 显著的海拔变化需要良好的体能水平

• 部分路段可能陡峭且具有挑战性

• 在您的技能范围内骑行

• 让某人知道您的计划路线和预计返回时间

🌤️ 天气预报（未来 4 小时）

路线亮点

• 从