bikescout 1.3.1

Professional MCP server for AI-powered cycling and mountain bike route discovery, terrain analysis, and GPX generation.

BikeScout MCP Server

BikeScout is a specialized MCP server for MTB, Road, E-Bike, and Gravel mission planning. It transforms raw map data into Tactical Intelligence, predicting terrain conditions and trail hazards. The system provides precise setup advice, tailoring your equipment to the demands of the specific route, identifying technical challenges and environmental risks before you even leave the garage.

---

Explore BikeScout

• User Guide Detailed API references and step-by-step guides to deploy the MCP server. Essential for developers integrating BikeScout into Claude, ChatGPT, or custom AI agents.

• Official Website A high-level overview of our predictive algorithms. Explore the visual breakdown of Mud Logic, S-Scale terrain grading, and how we transform raw OSM data into mission-ready intel.

Love BikeScout? ⭐ Star this repo to support the development of the first open-source tactical cycling engine.

Found a bug? Open an Issue. Want to add a local skill? PRs are welcome!

---

Example Queries

You can ask BikeScout complex, multi-step requests. It combines real-time data with technical cycling intelligence to provide expert-level answers.

🗺️ Advanced Planning (Multi-Tool)

• "I'm at Monte Cavo with my MTB bike (29 tires). Plan a 25km loop for me. Check if the terrain is compatible with my bike, verify the afternoon rain probability, and suggest a 'Fraschetta' for the finish. Use the Castelli Romani guide."

⚙️ Bike Setup & Surface Intelligence

• "Check this route from Barcelona city center to El Prat. I'm on a Road Bike with 25mm tires. Is it compatible? Give me the exact percentage of gravel vs asphalt."

📈 Visual Elevation & Gradient Analysis

• "Plan a 40km route starting from Bormio. I need the Visual Elevation Profile to see the exact gradients of the Stelvio climb. Highlight sections over 12% so I can manage my pacing."

🏔️ Local Expertise

• "Use the Derby local guide to plan a road cycling route starting from Derby. I need at least 800m of elevation gain. Also, recommend the correct tire pressure for high-altitude descents."

🛠️ Quick Tech Checks

• "Give me the safety checklist and calculate the tire pressure for a 90kg rider on 2.3" tubeless tires for a muddy ride."

🏁 Post-Ride Analysis & Terrain Truth

• "Analyze my ride from 2026-04-12. Compare my average speed with the Mud Risk at that time and tell me if the terrain conditions were the reason for my slow pace."

---

Quickstart: Deploy and Use BikeScout

Using Docker and OpenClaw

Pre Requirements:

• Docker Desktop: Download it here.
• OpenRouteService Key: Sign up here for trail and surface data.
• LLM Key: An API key from OpenAI or Anthropic to power the reasoning engine.

1. Download the repository: Download this repository as a ZIP and extract it to a folder (e.g., C:\BikeScout or /Users/YourName/BikeScout).
2. Rename .env.example to .env and paste your API keys:

ORS_API_KEY=your_ors_key_here
OPENAI_API_KEY=your_llm_key_here

3. Launch: Open your terminal in the folder and run:

docker-compose up -d

4. Access:

• On PC: Open http://localhost:3000
• On Smartphone: Connect to the same Wi-Fi, find your PC's IP (e.g., 192.168.1.15), and open http://192.168.1.15:3000.

To teardown the environment, execute:

docker compose down -v

Using Docker, Ollama and Open WebUI

If you prefer a private and free experience without external API costs, use the docker-compose-ollama.yml file to run BikeScout with Ollama (Llama 3/Mistral) instead of OpenAI. Refer to this guide to setup a complete local installation with Ollama and Open WebUI.

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

Pre Requirements:

• Python 3.10+
• OpenRouteService API Key: Get a free key at openrouteservice.org.
• MCP Client: Such as Claude Desktop, Cursor.

To integrate BikeScout with your preferred MCP client (Claude Desktop, Cline, Roo Code, etc.), add the following configuration to your settings file:

• Clone the repo in a local folder:

  git clone [e-mail]:hifly81/bikescout.git <your_local_folder_path>
  

• Create a Python Virtual Env from the local folder:

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

• Add the server to your claude_desktop_config.json:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

You must replace the placeholders in the JSON configuration with your local absolute paths to the Python script file. PATH/TO/YOUR/BIKESCOUT_FOLDER/src/bikescout/mcp_server.py

Example:

• 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",
      }
    }
  }
}

Debugging and Testing

You can test BikeScout using the MCP Inspector, a web-based tool for testing MCP servers.

Using the Inspector

To launch the inspector and interact with the tools manually, run the following command from the root directory:

export ORS_API_KEY=YOUR_OPENROUTE_SERVICE_API_KEY

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

What to check:

• List Tools: Ensure all tools (geocode_location, trail_scout, etc.) are visible.
• Run Tool: Test the geocode_location tool by passing a city name (e.g., "Rome") to verify the Nominatim integration.

---

🤝 Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make to BikeScout are greatly appreciated.

How to Contribute

1. Report Bugs: Found a glitch? Open an Issue with a detailed description and steps to reproduce.
2. Feature Requests: Have an idea to make BikeScout better? Open an issue to discuss it!
3. Pull Requests:
   • Fork the Project.
   • Create your Feature Branch (git checkout -b feature/AmazingFeature).
   • Commit your changes (git commit -m 'Add some AmazingFeature').
   • Push to the Branch (git checkout origin feature/AmazingFeature).
   • Open a Pull Request.

Coding Standards

• Please follow PEP 8 for Python code.
• Ensure all new tools are documented in the README.md.
• Keep comments in English for international collaboration.

By contributing, you agree that your contributions will be licensed under the project's AGPLv3 License.

---

License & Data Attributions

Software License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0) - see the LICENSE file for details.

Why AGPLv3?

BikeScout contains proprietary-grade tactical logic (such as the TAEL® Mud Reservoir Model). The AGPLv3 ensures that:

• Transparency: Any modified version of BikeScout used to provide a service over a network (SaaS/Cloud) must make its full source code available to the community.
• Integrity: The core tactical intelligence remains open and collaborative, preventing "closed-source" commercial hijacking of the platform's unique algorithms.

Data Sources & Credits

BikeScout aggregates data from several open providers. Users of this server must adhere to their respective terms:

• Routing & Map Data: Provided by OpenRouteService by HeiGIT.
• Geospatial & Geocoding Data: © OpenStreetMap contributors. Data is available under the Open Database License (ODbL). Geocoding service powered by Nominatim.
• Weather Forecasts: Powered by Open-Meteo. Data is licensed under CC BY 4.0.