Bicycle routes generator MCP

English · Español

⬇️ Download the Claude Desktop extension (bicycle-routes-generator-mcp.mcpb)

Generates mountain bike and road cycling routes from a location and saves them as GPX with elevation. The track is computed by a routing engine (BRouter or OpenRouteService) on real OpenStreetMap trails and roads: neither the AI nor the application invents coordinates.

You can use it:

• With Claude (Claude Desktop or Claude Code) through a local MCP server: "make me a ~25 km MTB loop from El Papiol, little climbing, on dirt tracks".

• From the terminal, without AI: bicycle-routes generate "El Papiol" --km 25 --type tracks.

Every route comes with a summary (distance, climbing, maximum grade, % of pavement, dirt track and singletrack) and warnings: sections with motor traffic, grades over 12 %, protected areas, ways where bikes are not allowed and technical sections.

💾 GPX files go to /tmp/bicycle-routes by default. macOS empties /tmp on restart and cleans up old files, so copy the routes you want to keep (or set BIKE_GPX_DIR to another folder).

⚠️ Always check the route on a map before riding. OpenStreetMap data may be incomplete or out of date, and does not reflect temporary closures or every local regulation. Climbing is computed from a digital elevation model (~90 m) and may differ from what a barometric watch or bike computer records (often by 10-20 %); short ramps may be smoothed out.

Easy install in Claude Desktop (.mcpb extension)

1. Download bicycle-routes-generator-mcp.mcpb (always the latest release), or build it with npx @anthropic-ai/mcpb pack . dist/bicycle-routes-generator-mcp.mcpb.

2. Double-click the file (or drag it into Claude Desktop → Settings → Extensions) and click Install.

3. Fill in the configuration: the GPX folder (/tmp/bicycle-routes by default) and a contact email (required by the OpenStreetMap/Nominatim usage policy). The other fields are optional.

4. Ask Claude: "make me a 25 km MTB loop from El Papiol on dirt tracks".

No need to install Python: this is a uv extension, so Claude Desktop downloads Python and the dependencies automatically the first time (it can take a minute). .mcpb is the successor of the .dxt format; older Claude Desktop versions that only support .dxt cannot run uv extensions.

Related MCP server: Valhalla MCP Server

Manual install (CLI and Claude Code)

Requirements: macOS, Windows or Linux with uv (it installs Python for you).

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)

There are no keys or personal data in the code: everything is configured through environment variables (or a .env file in the folder you run the CLI from).

Command-line usage

uv run bicycle-routes generate "El Papiol" --km 25 --type tracks --max-climb 500
uv run bicycle-routes generate "41.4386,2.0108" --km 15            # coordinates work too
uv run bicycle-routes generate "El Papiol" --km 20 --end "Sant Cugat del Vallès"   # point-to-point
uv run bicycle-routes generate "El Papiol" --km 30 --via "Castellbisbal" --via "Molins de Rei"  # loop through via points
uv run bicycle-routes generate "El Papiol" --km 40 --seed 7        # another reproducible alternative
uv run bicycle-routes generate "El Papiol" --km 25 --json          # JSON output
uv run bicycle-routes list

Trail types (--type):

• tracks: favours wide dirt tracks, little singletrack and no extreme ramps.

• mixed (default): general MTB.

• singletrack: more singletrack, less pavement.

• road: road bike. Paved roads with little traffic; warns about unpaved sections and only about busy roads (main roads or heavy estimated traffic), not ordinary secondary roads.

Real example (abridged):

MTB El Papiol 26 km loop
  Distance: 25.9 km · Climbing: +442 m / -443 m · Elevation 20–266 m
  Max grade: 17.0 % uphill, 18.0 % downhill
  Surface: paved 18.7 % · track 67.3 % · singletrack 14.1 %
  GPX: /tmp/bicycle-routes/mtb-el-papiol-26-km-loop-20261017-121732.gpx
  Warnings:
   - [traffic] 1.2 km on roads with motor traffic in 6 section(s); ride carefully.
   - [grade] 8 sections (about 2.2 km) are steeper than 12 %; listing the 6 steepest.
   - [protected_area] The route crosses the protected area «Parc Agrari del Baix Llobregat»…

More examples with real output in docs/pruebas-reales.md (in Spanish).

Using it with Claude (MCP server)

The server exposes two tools:

• generate_route(start, distance_km, max_climb_m?, trail_type?, loop=true, end?, name?, seed?, via?) → GPX path, summary and warnings. via is a list of places the route must pass through, in order (e.g. "a loop from El Papiol passing through Castellbisbal and Molins de Rei").

• list_routes() → saved routes.

Claude Code

claude mcp add bicycle-routes-generator-mcp \
  -e BIKE_GPX_DIR=/tmp/bicycle-routes -e BIKE_CONTACT=you@example.com \
  -- uv run --directory /path/to/bicycle-routes-generator-mcp bicycle-routes-mcp

Claude Desktop (without the extension)

The .mcpb extension is the easiest option (see above). To configure it by hand instead: 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": "you@example.com"
      }
    }
  }
}

Use the absolute path to uv (which uv on macOS/Linux, where uv on Windows), because Claude Desktop does not always inherit the terminal's PATH. Restart Claude Desktop.

Building the extension

manifest.json describes the extension (uv type, tools and configuration fields) and .mcpbignore keeps the tests, docs and your .env out of the package.

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

Publishing a release

1. Bump version in manifest.json, pyproject.toml and src/bicycle_routes/__init__.py together.

2. Create and push a matching tag:

   git tag v0.1.0
   git push origin v0.1.0

3. The Release GitHub Actions workflow runs the tests, builds bicycle-routes-generator-mcp.mcpb and attaches it to a new GitHub Release. The download link at the top of this README always points to the latest one.

Garmin, Wahoo and other platforms

The application is platform-independent: the output is a standard GPX file. Sending to platforms is done by optional exporters sharing a common interface (export(route, config) -> ExportResult, in src/bicycle_routes/exporters/).

• disk (default): saves the GPX in BIKE_GPX_DIR.

• garmin: delegates to an already installed Garmin MCP server (upload_course tool).

  • With Claude (recommended): nothing to configure. Ask "upload it to Garmin" and Claude will call the Garmin MCP server's upload_course with the generated GPX and activity_type="mountain_biking" ("road_biking" for road routes).

  • From the CLI: set BIKE_GARMIN_MCP_COMMAND to the command that starts that server and use --garmin. Garmin credentials are handled by that server, never by this app.

  • Community Garmin MCP servers use Garmin Connect's unofficial web API and may stop working. The official API (Courses API) is only available to approved businesses.

• wahoo: not implemented. The Cloud API has POST /v1/routes, but you must request an app and get it approved (notes in exporters/wahoo.py).

• Komoot (API only for partners under contract) and Strava (its API cannot create routes): import the GPX manually on their websites.

Routing engines

• BRouter (default, MIT, no key). Uses the mtb profile with StrictNOBicycleaccess=1 (avoids ways tagged bicycle=no) and avoid_unsafe=1; for road, the fastbike profile with consider_traffic=1 (the same routes as fastbike-lowtraffic). The public brouter.de server makes no availability guarantees: the app sends at most 1 request per second and caches responses. For heavy use, run a local one (not yet tested in this project):

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

• OpenRouteService (optional): BIKE_ENGINE=ors and ORS_API_KEY (free plan: 2,000 routes/day, 40/min). Profile cycling-mountain, or cycling-road for road.

How the loop is generated

1. The place is geocoded with Nominatim (or the coordinates you give are used).

2. 3-4 waypoints are placed on a circle passing through the start, with a random orientation (reproducible with --seed).

3. The engine routes start → waypoints → start on real trails.

4. The radius is adjusted until the requested distance is approached (about 2-4 requests).

5. Six candidates are generated and the best one is picked by distance, traffic, repeated trails, surface, forbidden access, climbing and grades.

With via points (--via / via), your points replace the random ones: the engine routes start → via 1 → … → via N → start (or → end, for point-to-point), in the given order. The distance comes from those points, not from --km; a warning is added if it differs by more than 15 %.

External services and their policies

• Nominatim (place lookup): usage policy. At most 1 request/second, an identifying User-Agent, cached results, no autocomplete or bulk queries. For heavy use, run your own Nominatim.

• Overpass API (protected areas): about 10,000 requests/day per IP as a guideline; one cached query per route.

• brouter.de: public server without guarantees; use a local one for heavy use.

Development

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

Layout:

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

The core does not depend on the CLI or the MCP server, so it could later be offered as a remote server (HTTP transport) by changing only the exporter and the transport.

License and attribution

Code under the MIT license. See NOTICE.

Trail and place data © OpenStreetMap contributors, under the ODbL license. Generated GPX files include this attribution in their metadata; keep it if you share them. BRouter elevation: SRTM (CGIAR-CSI).