Training Condition Check MCP server

<img width="1051" height="622" alt="Screenshot" src="https://github.com/user-attachments/assets/0cd45759-b659-47b7-a020-b9bfc334bb5b" />

Project Overview

This project aims to provide runners and outdoor enthusiasts with personalized recommendations for optimal outdoor exercise times based on weather conditions, training schedules from Garmin Connect, and individual performance metrics. It is internal development task for Jangtse Runners club.

Key features include:

• Integration with weather service for real-time weather data. (Currently using OpenWeatherMap API)
• Synchronization with Sport Communities to fetch training plans and user performance metrics. (Currently using Garmin Connect)
• Recommendations for best time windows for outdoor activities based on weather and training plans.

MCP Tools

• Get Outdoor Running Time Window of Today for a Specific Location Function: Finds outdoor Training windows for a specific location, avoiding bad weather conditions.

• Get Local Outdoor Exercise Time Window for Today Function: Automatically detects the user's current location via IP address and finds suitable time windows for outdoor exercise today.

• Get Next Training in Garmin Connect Function: Retrieves the current training in current week plan from Garmin Connect.

• Get Activities of Current Month in Garmin Connect Function: Retrieves all activities (including training and recorded activities) for the current month from Garmin Connect.

• No-Go Conditions for Outdoor Exercise Function: Retrieves the current filter of weather conditions that are not suitable for outdoor exercise based on environment variables.

System Features

1. Location-Based Weather Queries: Fetch current and forecasted weather data for a given location.
2. Garmin Connect Integration: Retrieve training schedules and user statistics.
3. Optimal Time Window Calculation: Combine weather forecasts and training schedules to recommend ideal exercise periods.

Technical Architecture

The primary modules include:

• garmin_connect.py: Handles interactions with Garmin Connect, which uses Garth for authentication.
• openweathermap.py: Manages interactions with OpenWeatherMap.
• server.py: Implements the core MCP server.

Installation and Setup

{
    "mcpServers": {
        "Training_Condition_Check": {
            "command": "<local git repo>\\.venv\\Scripts\\python>",
            "args": [
                "<local git repo>\\src\\training_condition_check_mcp_server\\server.py"
            ],
            "env": {
                "GARMIN_CONNECT_LOGIN": "<your email as garmin connect login>",
                "GARMIN_CONNECT_PASSWORD": "<your garmin connect password>",
                "OPENWEATHER_API_KEY": "<your OPENWEATHER_API_KEY>",
                "UNHEALTHY_WEATHER_CONDITIONS": "rain,snow,thunderstorm"
            }
        }
    }
}

Environment Variables:

• UNHEALTHY_WEATHER_CONDITIONS: Comma-separated list of weather conditions to avoid (default: no avoidance).

Prerequisites:

• UV for Python environment, e.g., uv sync
• Garmin connect account
• openweathermap API key

Known Issues and Future Work

• Currently, weather conditions are incomplete; future updates will handle additional adverse weather types.
• Documentation is still under development.
• Support for additional weather services and sport communities is planned.