Bicycle routes generator MCP

Bicycle routes generator MCP

英語 · スペイン語

⬇️ Claude Desktop 拡張機能をダウンロード（bicycle-routes-generator-mcp.mcpb）

場所を指定して、マウンテンバイクおよびロードサイクリングのルートを生成し、標高情報付きの GPX として保存します。ルートは、実際の OpenStreetMap のトレイルや道路を対象に、ルーティングエンジン（BRouter または OpenRouteService）が計算します。AI もアプリケーションも座標を捏造しません。

次の方法で利用できます。

• Claude で（Claude Desktop または Claude Code）、ローカル MCP サーバーを通じて：「マドリードのカサ・デ・カンポから、登りが少なく、未舗装路を走る約 25 km の MTB ループを作って」（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 に尋ねます：「マドリードのカサ・デ・カンポから、未舗装路を走る 25 km の MTB ループを作って」。

Python をインストールする必要はありません。これは uv 拡張機能なので、初回起動時に Claude Desktop が Python と依存関係を自動的にダウンロードします（1 分ほどかかる場合があります）。.mcpb は .dxt 形式の後継です。.dxt のみをサポートする古いバージョンの Claude Desktop では、uv 拡張機能を実行できません。

手動インストール（CLI と Claude Code）

必要条件：uv がインストールされた 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

Configuration (environment variables)

コード内にキーや個人データはありません。すべて環境変数（または CLI を実行するフォルダー内の .env ファイル）で設定します。

Variable	Default	Purpose
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（デフォルト）：一般的な MTB です。
• 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 サーバー）

サーバーは次の 2 つのツールを公開します。

• 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 に尋ねるとどうなるか

あなた： 「マドリードのカサ・デ・カンポ発で、約40 kmのMTB周回コースを作ってください。」

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 を指定して再現可能にしています。シードを指定しない場合、リクエストごとに異なる周回コースが生成されます）。

{
  "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 の表現は異なります）。

カサ・デ・カンポ発の37.8 kmの周回コースを作成しました。獲得標高は**+336 mで、未舗装路が41％、シングルトラックが31％、舗装路が29％です。交通量のある道路を0.3 km走る区間（27.3～27.6 km地点）と、9.2 km地点にある勾配約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 を追加します
「エル・パルドを経由してください」	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. 2つ目のジョブが、そのバージョンを公式の MCP Registry に io.github.Marc-Armillas/bicycle-routes-generator-mcp として公開します。server.json にバージョン、リリース URL、.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 が生成された GPX と activity_type="mountain_biking"（ロードルートの場合は "road_biking"）を指定して、Garmin MCP サーバーの upload_course を呼び出します。
  • CLI から使う場合：そのサーバーを起動するコマンドを BIKE_GARMIN_MCP_COMMAND に設定し、--garmin を指定します。Garmin の認証情報はそのサーバーが処理し、このアプリが扱うことはありません。
  • コミュニティ製の Garmin MCP サーバーは、Garmin Connect の非公式ウェブ API を使用しているため、動作しなくなる可能性があります。公式 API（Courses API）は、承認を受けた企業のみ利用できます。
• wahoo：未実装です。Cloud API には POST /v1/routes がありますが、アプリを申請し、承認を受ける必要があります（exporters/wahoo.py の注記を参照）。
• Komoot（API は契約を結んだパートナーのみ利用可能）と Strava（API でルートを作成できません）：各ウェブサイトから GPX を手動でインポートしてください。

ルーティングエンジン

• BRouter（デフォルト、MIT、API キー不要）。StrictNOBicycleaccess=1（bicycle=no タグの付いた道を回避）および avoid_unsafe=1 を指定した mtb プロファイルを使用します。road の場合は、consider_traffic=1 を指定した fastbike プロファイルを使用します（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 を設定します（無料プラン：1 日あたり 2,000 ルート、1 分あたり 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 アドレスごとに 1 日あたり約 10,000 件のリクエストが可能です。ルートごとにキャッシュされたクエリを 1 件使用します。
• 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

コアは CLI や MCP サーバーに依存していないため、エクスポーターとトランスポートだけを変更すれば、後からリモートサーバー（HTTP トランスポート）として提供できます。

ライセンスと帰属表示

コードは MIT ライセンスの下で提供されています。NOTICE を参照してください。

トレイルと場所のデータは OpenStreetMap のコントリビューターに著作権があり、ODbL ライセンスの下で提供されています。 生成された GPX ファイルのメタデータにはこの帰属表示が含まれています。共有する場合は削除しないでください。BRouter の標高データ：SRTM（CGIAR-CSI）。