Bicycle routes generator MCP

自行车路线生成器 MCP

English · 西班牙语

⬇️ 下载 Claude Desktop 扩展（bicycle-routes-generator-mcp.mcpb）

根据地点生成山地自行车和公路骑行路线，并将其保存为带有海拔数据的 GPX 文件。路线由路线规划引擎（BRouter 或 OpenRouteService）在真实的 OpenStreetMap 小径和道路上计算得出：AI 和应用程序都不会虚构坐标。

你可以这样使用：

• 通过 Claude 使用（Claude Desktop 或 Claude Code），连接本地 MCP 服务："从马德里的 Casa de Campo 出发，帮我规划一条约 25 km 的山地自行车环线，爬坡少，走土路"（参见向 Claude 提问时会发生什么）。
• 通过终端使用，无需 AI：bicycle-routes generate "Casa de Campo, Madrid" --km 25 --type tracks。

每条路线都附有摘要（距离、爬升、最大坡度、路面铺装比例、土路和单车道比例）以及警告：有机动车通行的路段、坡度超过 12 % 的路段、保护区、自行车禁行路段和技术路段。

💾 GPX 文件默认保存在 /tmp/bicycle-routes。 macOS 重启时会清空 /tmp 并删除旧文件，因此请复制要保留的路线（或将 BIKE_GPX_DIR 设置为其他文件夹）。

⚠️ 骑行前务必在地图上检查路线。 OpenStreetMap 数据可能不完整或已过时，也无法反映临时封闭或所有当地法规。爬升数据根据数字高程模型（约 90 m）计算，可能与气压手表或自行车码表的记录不同（通常相差 10-20 %）；较短的陡坡可能会被平滑处理。

在 Claude Desktop 中轻松安装（.mcpb 扩展）

1. 下载 bicycle-routes-generator-mcp.mcpb（始终为最新版本），或使用 npx @anthropic-ai/mcpb pack . dist/bicycle-routes-generator-mcp.mcpb 构建。
2. 双击该文件（或将其拖入 Claude Desktop → 设置 → 扩展），然后点击安装。
3. 填写配置：GPX 文件夹（默认为 /tmp/bicycle-routes）和联系邮箱（OpenStreetMap/Nominatim 使用政策要求提供）。其他字段均为可选。
4. 向 Claude 提问："从马德里的 Casa de Campo 出发，帮我规划一条 25 km 的山地自行车环线，走土路"。

无需安装 Python：这是一个 uv 扩展，因此 Claude Desktop 会在首次使用时自动下载 Python 和依赖项（可能需要一分钟）。.mcpb 是 .dxt 格式的后继格式；仅支持 .dxt 的旧版 Claude Desktop 无法运行 uv 扩展。

手动安装（CLI 和 Claude Code）

要求：运行 macOS、Windows 或 Linux，并安装 uv（它会为你安装 Python）。

git clone <repository-url> bicycle-routes-generator-mcp
cd bicycle-routes-generator-mcp
uv sync
cp .env.example .env   # and edit it

配置（环境变量）

代码中不包含任何密钥或个人数据：所有内容均通过环境变量配置 （或通过你运行 CLI 的文件夹中的 .env 文件配置）。

变量	默认值	用途
BIKE_GPX_DIR	/tmp/bicycle-routes	保存 GPX 文件的文件夹。应用只会写入此处（以及其中用于缓存和索引的 .bicycle-routes/ 子文件夹）。在 Windows 上，默认值为系统临时文件夹。
BIKE_CONTACT	—	在 User-Agent 中发送的电子邮件地址或 URL。建议设置：Nominatim 的政策要求提供此项。
BIKE_ENGINE	brouter	brouter 或 ors。
BIKE_BROUTER_URL	https://brouter.de	BRouter 服务（公共服务或本地服务，见下文）。
ORS_API_KEY	—	使用 BIKE_ENGINE=ors 时所需的免费 OpenRouteService 密钥。
BIKE_PROTECTED_AREAS	1	通过 Overpass API 检查保护区。
BIKE_GARMIN_MCP_COMMAND	—	仅用于 CLI 中的 --garmin（见“Garmin”）。
BIKE_DATA_DIR	<GPX folder>/.bicycle-routes	缓存和索引的存放位置。

命令行用法

uv run bicycle-routes generate "Casa de Campo, Madrid" --km 25 --type tracks --max-climb 500
uv run bicycle-routes generate "40.4242,-3.7559" --km 15            # coordinates work too
uv run bicycle-routes generate "Casa de Campo, Madrid" --km 20 --end "El Pardo, Madrid"   # point-to-point
uv run bicycle-routes generate "Casa de Campo, Madrid" --km 30 --via "El Pardo, Madrid" --via "Aravaca, Madrid"  # loop through via points
uv run bicycle-routes generate "Madrid" --km 60 --type road         # road bike
uv run bicycle-routes generate "Casa de Campo, Madrid" --km 40 --seed 7   # another reproducible alternative
uv run bicycle-routes generate "Casa de Campo, Madrid" --km 25 --json     # JSON output
uv run bicycle-routes list

路线类型（--type）：

• tracks：优先选择宽阔的土路，少走单轨道，不走极端陡坡。
• mixed（默认）：通用山地自行车路线。
• singletrack：增加单轨道，减少铺装路面。
• road：公路自行车路线。选择车流较少的铺装道路；对未铺装路段和繁忙道路（主干道或预估车流量大的道路）发出警告，但不会对普通次要道路发出警告。

真实示例（节选）：

MTB Casa de Campo 38 km loop
  Start: Casa de Campo, Madrid, Comunidad de Madrid, España
  Distance: 37.8 km · Climbing: +336 m / -338 m · Elevation 615–725 m
  Max grade: 10.3 % uphill, 13.3 % downhill
  Surface: paved 28.8 % · track 40.6 % · singletrack 30.6 %
  Engine: brouter (mtb) · candidates evaluated: 6
  GPX: /tmp/bicycle-routes/mtb-casa-de-campo-38-km-loop-20261017-163919.gpx
  Warnings:
   - [traffic] 0.3 km on roads with motor traffic in 1 section(s); ride carefully.
   - [traffic] Road with traffic (km 27.3–27.6).
   - [grade] Steep descent over 12 % (max ~13 %, km 9.2–9.3).
   - [general] Climbing and grades come from a digital elevation model (~90 m resolution)…
   - [general] Route generated automatically from OpenStreetMap: check it on a map before riding…

更多包含真实输出的示例见 docs/pruebas-reales.md（西班牙语）。

与 Claude 搭配使用（MCP 服务）

该服务提供两个工具：

• generate_route(start, distance_km, max_climb_m?, trail_type?, loop=true, end?, name?, seed?, via?) → GPX 路径、摘要和警告。via 是一个地点列表，路线必须按顺序经过这些地点（例如“从 Casa de Campo 出发，经过 El Pardo 和 Aravaca 的环线”）。
• list_routes() → 已保存的路线。

示例：向 Claude 提问时会发生什么

你： “帮我规划一条从马德里 Casa de Campo 出发、约 40 km 的山地车环线。”

1. Claude 调用工具，根据你的请求选择参数：

generate_route({ "start": "Casa de Campo, Madrid", "distance_km": 40, "trail_type": "mixed" })

2. MCP 服务在你的电脑上计算路线（10–60 秒）：

1. 在 Nominatim（OpenStreetMap）中查找“Casa de Campo, Madrid” → 40.424, -3.756。
2. 使用 BRouter 在真实步道上生成 6 条候选环线，并将每条路线调整到约 40 km。
3. 为路线评分（距离、交通、重复路段、路面、禁止通行路段、爬升），并 保留评分最高的一条。
4. 分析路线：爬升、坡度、路面、有交通的路段、技术路段和 保护区（Overpass API）。
5. 将包含海拔数据的 GPX 文件保存到你的 GPX 文件夹。

3. 它将以下内容返回给 Claude（真实输出，已删节；使用 "seed": 2026 生成，因此可以 复现：不指定 seed 时，每次请求都会生成不同的环线）：

{
  "name": "MTB Casa de Campo 38 km loop",
  "gpx_file": "/tmp/bicycle-routes/mtb-casa-de-campo-38-km-loop-20261017-163919.gpx",
  "start": { "name": "Casa de Campo, Madrid, Comunidad de Madrid, España", "lat": 40.4241907, "lon": -3.755858 },
  "summary": {
    "distance_km": 37.8, "ascent_m": 336, "descent_m": 338,
    "min_elevation_m": 615, "max_elevation_m": 725,
    "max_uphill_grade_pct": 10.3, "max_downhill_grade_pct": 13.3,
    "surface_pct": { "paved": 28.8, "track": 40.6, "path": 30.6, "unknown": 0.0 },
    "warnings": [
      { "kind": "traffic", "message": "0.3 km on roads with motor traffic in 1 section(s); ride carefully." },
      { "kind": "traffic", "message": "Road with traffic (km 27.3–27.6).", "start_km": 27.32, "end_km": 27.61 },
      { "kind": "grade", "message": "Steep descent over 12 % (max ~13 %, km 9.2–9.3).", "start_km": 9.22, "end_km": 9.34 },
      { "kind": "general", "message": "Climbing and grades come from a digital elevation model (~90 m resolution)…" },
      { "kind": "general", "message": "Route generated automatically from OpenStreetMap: check it on a map before riding…" }
    ]
  },
  "engine": "brouter (mtb)",
  "activity_type": "mountain_biking",
  "candidates_evaluated": 6,
  "attribution": "Trail data © OpenStreetMap contributors (ODbL) — https://www.openstreetmap.org/copyright"
}

4. Claude 用你的语言回答，提供摘要和所有警告。例如 （仅供参考，Claude 的措辞会有所不同）：

我规划了一条从 Casa de Campo 出发的37.8 km 环线，爬升 +336 m：41％为土路， 31％为单轨山道，29％为铺装路面。请注意，有 0.3 km 路段在有交通的道路上 （km 27.3–27.6），并且 km 9.2 处有一段约 13％的陡坡下坡。爬升数据来自海拔 模型，可能与你的手表数据不同，因此骑行前请先在地图上检查路线。 GPX：/tmp/bicycle-routes/mtb-casa-de-campo-38-km-loop-20261017-163919.gpx

之后，你可以在同一段对话中继续提出要求：

你说	Claude 的操作
“再给我一个选项”	使用不同的 seed 再次调用 generate_route
“少爬坡，最多 200 m”	添加 max_climb_m: 200
“让路线经过 El Pardo”	添加 via: ["El Pardo, Madrid"]
“现在从马德里出发，骑一条 60 km 的公路路线”	使用 trail_type: "road"（铺装路面、交通较少）
“把它上传到 Garmin”	如果已安装 Garmin MCP 服务，则使用 GPX 调用其 upload_course
“我保存了哪些路线？”	调用 list_routes

Claude Code

claude mcp add bicycle-routes-generator-mcp \
  -e BIKE_GPX_DIR=/tmp/bicycle-routes -e [email protected] \
  -- uv run --directory /path/to/bicycle-routes-generator-mcp bicycle-routes-mcp

Claude Desktop（不使用扩展）

.mcpb 扩展是最简单的选项（见上文）。若要改为手动配置： Settings → Developer → Edit config（claude_desktop_config.json）：

{
  "mcpServers": {
    "bicycle-routes-generator-mcp": {
      "command": "/absolute/path/to/uv",
      "args": ["run", "--directory", "/path/to/bicycle-routes-generator-mcp", "bicycle-routes-mcp"],
      "env": {
        "BIKE_GPX_DIR": "/tmp/bicycle-routes",
        "BIKE_CONTACT": "[email protected]"
      }
    }
  }
}

请使用 uv 的绝对路径（macOS/Linux 上运行 which uv，Windows 上运行 where uv），因为 Claude Desktop 不一定会继承终端的 PATH。重启 Claude Desktop。

构建扩展

manifest.json 描述扩展（uv 类型、工具和配置字段），而 .mcpbignore 会将测试、文档和你的 .env 排除在软件包之外。

npx @anthropic-ai/mcpb validate manifest.json
npx @anthropic-ai/mcpb pack . dist/bicycle-routes-generator-mcp.mcpb
python scripts/make_icon.py    # only if you want to regenerate icon.png

发布版本

1. 同时更新 manifest.json、pyproject.toml 和 src/bicycle_routes/__init__.py 中的 version。

2. 创建并推送匹配的标签：

   git tag v0.1.0
   git push origin v0.1.0
   

3. Release GitHub Actions 工作流会运行测试、构建 bicycle-routes-generator-mcp.mcpb，并将其附加到新的 GitHub Release。 本 README 顶部的下载链接始终指向最新版本。

4. 第二个任务会将该版本发布到官方 MCP Registry，名称为 io.github.Marc-Armillas/bicycle-routes-generator-mcp：它会在 server.json 中填写 版本、发布链接和 .mcpb 的 SHA-256，并使用 GitHub OIDC 登录（无需密钥）。 如果注册表拒绝该版本，GitHub Release 仍已发布。

Garmin、Wahoo 和其他平台

此应用与平台无关：输出为标准 GPX 文件。通过可选的 导出器 发送到各个平台；它们共享同一个接口 （export(route, config) -> ExportResult，位于 src/bicycle_routes/exporters/）。

• disk（默认）：将 GPX 保存到 BIKE_GPX_DIR。
• garmin：委托给已安装的 Garmin MCP 服务（upload_course 工具）。
  • 使用 Claude（推荐）：无需配置。只需说“上传到 Garmin”，Claude 就会调用 Garmin MCP 服务的 upload_course，并传入生成的 GPX 和 activity_type="mountain_biking"（公路路线则为 "road_biking"）。
  • 通过命令行使用：将 BIKE_GARMIN_MCP_COMMAND 设置为启动该服务的命令，并使用 --garmin。Garmin 凭据由该服务处理，不会交给此应用处理。
  • 社区提供的 Garmin MCP 服务使用 Garmin Connect 的非官方 Web API，可能会停止工作。 官方 API（Courses API）仅向获批企业开放。
• wahoo：尚未实现。Cloud API 提供 POST /v1/routes，但你必须申请应用并获得批准（说明见 exporters/wahoo.py）。
• Komoot（API 仅面向签约合作伙伴）和 Strava（其 API 无法创建路线）：请在各自网站上手动导入 GPX。

路线规划引擎

• BRouter（默认，MIT，无需密钥）。使用 mtb 配置文件和 StrictNOBicycleaccess=1 （避开标记为 bicycle=no 的道路），并设置 avoid_unsafe=1；对于 road，使用 fastbike 配置文件 和 consider_traffic=1（与 fastbike-lowtraffic 路线相同）。公共 brouter.de 服务器不保证可用性：此应用每秒最多发送 1 个请求，并会缓存响应。 如需大量使用，请运行本地实例（本项目尚未测试）：

  mkdir -p segments4
  curl -o segments4/W5_N40.rd5 https://brouter.de/brouter/segments4/W5_N40.rd5   # Madrid and central Spain
  docker run -d -p 17777:17777 -v "$PWD/segments4:/segments4" ghcr.io/abrensch/brouter
  # and in .env: BIKE_BROUTER_URL=http://localhost:17777
  

• OpenRouteService（可选）：设置 BIKE_ENGINE=ors 和 ORS_API_KEY（免费套餐：每天 2,000 条路线，每分钟 40 条）。使用 cycling-mountain 配置文件；对于 road，使用 cycling-road。

环线的生成方式

1. 使用 Nominatim 对地点进行地理编码（或直接使用你提供的坐标）。
2. 在经过起点的圆上放置 3-4 个航点，并随机选择方向 （可通过 --seed 重现）。
3. 路线规划引擎在真实步道上规划起点 → 航点 → 起点的路线。
4. 调整半径，直到接近所需距离（约需 2-4 次请求）。
5. 生成 6 个候选路线，并根据距离、交通、步道重复情况、路面、禁行限制、爬升和坡度选出最佳路线。

使用途经点（--via / via）时，你提供的点会取代随机航点：路线规划引擎按指定顺序规划起点 → 途经点 1 → … → 途经点 N → 起点（点到点路线则为 → 终点）。路线距离根据这些点计算，而不是根据 --km 计算；如果相差超过 15 %，会添加警告。

外部服务及其政策

• Nominatim（地点查询）：使用政策。 每秒最多 1 个请求，必须使用可识别的 User-Agent，缓存结果，不进行自动补全或批量查询。 如需大量使用，请运行自己的 Nominatim。
• Overpass API（保护区）：通常每个 IP 每天约可发起 10,000 个请求；每条路线会使用一个缓存查询。
• brouter.de：无可用性保证的公共服务器；如需大量使用，请使用本地实例。

开发

uv run pytest              # tests with simulated engine, geocoder and areas (no network)
uv run pytest -m network   # optional test against the real services

目录结构：

src/bicycle_routes/
├── core/            # models, loop generator, analysis and GPX (no network, no platforms)
├── engines/         # BRouter and OpenRouteService (RoutingEngine interface)
├── geo/             # Nominatim and protected areas (Overpass)
├── exporters/       # disk, garmin (via MCP), wahoo (pending)
├── net.py           # HTTP client: User-Agent, rate limiting, retries and cache
├── service.py       # reusable orchestration (CLI, MCP and a future remote server)
├── mcp_server.py    # MCP server (stdio)
└── cli.py

核心部分不依赖命令行或 MCP 服务，因此以后只需更换导出器和传输方式，就可以将其作为远程服务（HTTP 传输）提供。

许可证和归属信息

代码采用 MIT 许可证。请参阅 NOTICE。

步道和地点数据 © OpenStreetMap 贡献者，遵循 ODbL 许可证。 生成的 GPX 文件会在元数据中包含此归属信息；分享文件时请保留。BRouter 高程数据：SRTM（CGIAR-CSI）。