BikeScout

The AI Engine that turns raw geodata into Predictive Intel.
Plan with certainty and scout the terrain before you ride: analyze soil drainage, wind vectors, and technical grade before you drop in.

View on GitHub
pip install bikescout

Understanding BikeScout

What is BikeScout?

BikeScout isn't just a map tool; it's a Tactical Intelligence Engine. It transforms static geographical data (OSM) into actionable insights by simulating real-world physics, weather history, and technical terrain difficulty.

Whether you are planning a gravel expedition or an E-MTB mission, BikeScout calculates the "hidden variables" that generic navigators ignore.

What is an MCP Server?

The Model Context Protocol (MCP) is an open standard that allows AI agents (like Claude, ChatGPT or Ollama) to use external tools safely and efficiently.

By running BikeScout as an MCP server, you give your AI the "eyes" to see trails, "hands" to generate GPX files, and the "brain" to analyze soil conditions, turning a simple LLM into a professional cycling scout.

Core Capabilities

Terrain Intelligence

Bridging the gap between maps and reality.

  • Trail Discovery: AI-driven extraction of trail names and surface types via Overpass API.
  • S-Scale Grading: Technical classification of trails from S0 (easy) to S5 (extreme).
  • Surface Matrix: Provides a precise percentage breakdown of asphalt vs. gravel vs. singletrack.

Environmental Modeling

Predicting the unpredictable.

  • TAEL™ Logic: Terrain-Aware Evaporation Lag to predict "Shadow-Lock" (mud that never dries).
  • Mud Risk Score: Analysis based on soil drainage and the last 72h of precipitation.
  • Ride Window: AI suggests the optimal start time based on heat, wind, and light.

Tactical Navigation

Precision routing for AI agents.

  • Wall-Sense: Automatic detection of gradients >10% with localized waypoint alerts.
  • UCI Climb Categorization: Classifies ascents from Cat 4 to the brutal Hors Catégorie.
  • Noise-Free GPX: Generates clean, tactical GPX files optimized for GPS devices.

Logistics & Physics

Energy management for man and machine.

  • E-MTB Wh Modeling: Precise battery drain estimation based on rider weight and assist mode.
  • VAM Analysis: Calculates required W/kg to maintain specific climbing speeds.
  • Strategic POIs: Scans a 5km radius for water points, repair kits, and shelters.

Why BikeScout?

Standard navigation tools like Google Maps or Komoot are designed for simple "lines on a map." BikeScout is built for Mission Planning, bridging the gap between raw data and technical reality.

Feature Generic Navigators BikeScout Tactical AI
Elevation Accuracy Raw & Inflated Filtered & Realistic (SMA)
Surface Analysis Basic (Paved/Dirt) Technical (S-Scale/Tracktype)
Effort Calculation Time-based average Physics-based (Weight/Friction)
Condition Prediction Future Weather only Mud Risk (72h Rain + Soil Memory)
Climb Categorization None UCI-Standard (Cat 4 to HC)
Logistics Sponsored / Restaurants Tactical (Water/Repair/Shelter)
AI Integration Manual / External Native MCP Tooling

Deploy and Use BikeScout

Follow these sections to deploy BikeScout in your environment.

Using the BikeScout GUI

Pre-Requirements:

  • • Python 3.10+
  • • OpenRouteService Key: Sign up for obtaining a free key.
BikeScout GUI
BikeScout GUI

The BikeScout Tactical GUI is a high-performance, interactive control center designed for cyclists and trail scouts who need real-time, data-driven mission planning. Built on top of the Streamlit framework, it serves as a bridge between localized Large Language Models (LLMs) and specialized tactical tools.

Unlike a standard chat interface, this GUI is an Intelligence Dispatcher: it translates natural language requests into precise parameters for geospatial analysis, weather windowing, and physiological fueling plans.

Core Capabilities

  • • On-Device Intelligence: Runs fully local LLMs (like Llama 3.1) via llama-cpp-python, ensuring your mission data stays private and functions without an internet connection.
  • • Tactical Visualizations: Automatically renders high-resolution maps, elevation profiles, and weather trend charts directly within the conversation.
  • • Modular Intelligence (MCP): Orchestrates diverse data sources including geospatial engines, TAEL© Mud Risk predictive soil analysis, and Strategic Nutrition fueling targets.
  • • Dynamic Briefings: Generates structured briefings with downloadable GPX files, mechanical setup advice (tire pressure), and safety warnings.

How to use the GUI:

  1. Launch the GUI: Run the following command from your terminal:
    streamlit run src/bikescout/app.py

    The application will open in your default browser at: http://localhost:8501/

  2. Configure OpenRouteService API Key: Navigate to the Configuration section in the left sidebar and enter your ORS_API_KEY.
  3. Download LLM Engine: Select and download a supported model.

    Note: Ensure you have approx. 5GB - 8GB of free disk space.

    • Llama-3-8B (Standard)
    • Llama-3.1-8B-Instruct (Advanced)
  4. Analyze & Deploy: Once the download is complete, enter your mission parameters.

Prompt Example:

"Find a route of approximately 25 km nearby Albano Laziale, Rome, Italy. I'm riding a 29-inch wheel bike. Include POIs, weather, nutrition, mud analysis, GPX export, map, and altimetry."

Using an MCP client (e.g. Claude Desktop, Cursor, Google Antigravity)

Pre-Requirements:

  • • Python 3.10+
  • • OpenRouteService Key: Sign up for obtaining a free key.
  • • MCP Client: Such as Claude Desktop, Cursor, Google Antigravity, Codex, Windsurf.

To integrate BikeScout with your preferred MCP client (e.g. Claude Desktop, Cursor, Google Antigravity), add the following configuration to your settings file:

  1. Clone the repository:
    git clone git@github.com:hifly81/bikescout.git
  2. Create a Python virtual environment:
    python3 -m venv venv
  3. Activate the Python virtual environment:
    source venv/bin/activate
  4. Install the BikeScout package:
    pip install bikescout

Add the server to your MCP client config file:

  1. Claude Desktop: .claude/settings.json
  2. Cursor: .cursor/mcp.json
  3. Google Antigravity: .gemini/antigravity/mcp_config.json
  4. Codex: .codex/config.toml
  5. Windsurf: .codeium/windsurf/mcp_config.json 
{
  "mcpServers": {
    "bikescout": {
      "command": "PATH/TO/YOUR/PYTHON_VENV",
      "args": ["-u", "-m", "bikescout.mcp_server"],
      "env": {
        "PYTHONPATH": "PATH/TO/SRC",
        "ORS_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Configure Skills in your MCP Client

Pre-Requirements:

  • • MCP Client: Such as Claude Desktop, Cursor, Google Antigravity, Codex, Windsurf.

To integrate BikeScout Skills with your preferred MCP client (e.g. Claude Desktop, Cursor, Google Antigravity), follow these steps:

  1. Clone the repository:
    git clone git@github.com:hifly81/bikescout.git

Add the .agents/skills folder in the following locations:

  1. Cursor: ~/.agents/skills
  2. Google Antigravity: ~/.gemini/antigravity/skills
  3. Codex: ~/.agents/skills

Using Docker and OpenClaw

Pre-Requirements:

  • • Docker Desktop: Download here
  • • OpenRouteService Key: Sign up for trail data
  • • LLM Key: OpenAI or Anthropic API Key
  1. Download the repository as a ZIP and extract it.
  2. Rename .env.example to .env and paste keys:
    ORS_API_KEY=your_ors_key_here
    OPENAI_API_KEY=your_llm_key_here
  3. Run:
    docker-compose up -d
  4. Access:
    http://localhost:3000
  5. To stop the environment, Run:
    docker-compose down

Using Docker, Ollama and Open WebUI

If you prefer a private and free experience without external API costs.

Pre-Requirements:

  1. Download the repository as a ZIP and extract it.
  2. Rename .env.example to .env and paste keys:
    ORS_API_KEY=your_ors_key_here
  3. Run:
    docker compose -f docker-compose-ollama.yml up -d
  4. Download a LLM model for Ollama, example llama3.1:8b:
    docker exec -it ollama ollama pull llama3.1:8b
  5. Launch Open WebUI:
    http://localhost:3000
    and follow the instructions to create a first user.
  6. To stop the environment, Run:
    docker-compose -f docker-compose-ollama.yml down

To integrate the MCP tools within the Open WebUI interface, follow these steps:

  • Navigate: Go to Admin Panel Settings Integrations.
  • Add Connection: Click the + button and fill the following:
Field Tactical Value
TypeOpenAPI
URLhttp://mcpo:8000/bikescout
OpenAPI SpecSet to URL and use openapi.json
AuthNone
ID / Namebikescout

Once saved, you can enable this tool for your specific models in the New Chat, Workspace or Model settings, allowing the LLM to access real-time data through your MCP server.

Debugging and Testing

You can test BikeScout using the MCP Inspector, a web-based tool for testing MCP servers. To launch the inspector and interact with the tools manually, run the following command from the root directory:

  1. SET ORS_API_KEY as environment variable:
    export ORS_API_KEY=YOUR_KEY
  2. Launch MCP Inspector:
    PYTHONPATH=./src npx @modelcontextprotocol/inspector ./venv/bin/python3 -m bikescout.mcp_server

Automated Unit Tests & Coverage

Run the test suite with pytest:

  1. Run all tests:
    python -m pytest
  2. Run with Coverage Report (Term + HTML):
    python -m pytest --cov=src/bikescout --cov-report=term-missing

Note: Local tests are executed using the virtual environment's Python interpreter to ensure dependency alignment with the production MCP server.

BikeScout @ 2026 // hifly81
Licensed under AGPL-3.0 // Data by OSM - ORS - Open-Meteo
Disclaimer: Tactical models are simulations // Verify conditions in person // Ride at your own risk