Strava Training MCP

Strava Training MCP

A comprehensive Model Context Protocol (MCP) server that provides full access to the Strava API, specifically designed for marathon training and race analysis. This server enables language models to query detailed athlete data, analyze training patterns, track performance metrics, and plan races.

Features

• Comprehensive Activity Data: Access detailed activity information including pace, heart rate, power, cadence, GPS coordinates, and more
• Training Analysis: Weekly and monthly training metrics, pace trends, and long run analysis
• Detailed Streams: Time-series data for analyzing performance throughout activities
• Laps & Splits: Analyze pace consistency and splits for race preparation
• Zone Analysis: Heart rate and power zone data for training intensity analysis
• Athlete Statistics: Year-to-date totals, personal records, and achievement tracking
• Marathon Training Tools: Heart rate zone analysis, training load monitoring, injury risk detection, and recovery analysis
• Built-in Authentication: Streamlined OAuth flow with MCP tools - no separate scripts needed
• Multiple Transports: Support for stdio, SSE, and streamable-http transports

Installation

Using uv (Recommended)

# Clone the repository
git clone <your-repo-url>
cd strava-training-mcp

# Install dependencies
uv sync

# Run the server
uv run src/server.py --transport sse --port 9186

Using pip

pip install strava-training-mcp

Quick Start

1. Get Strava API credentials from Strava API Settings
2. Start the server (it will guide you through authentication)
3. Use MCP tools to authenticate and query your Strava data

See QUICK_START.md for detailed authentication instructions.

Available Tools

Authentication & Setup

• get_strava_auth_token(client_id, client_secret, auth_code): Complete authentication in one step (recommended)
• save_credentials(client_id, client_secret): Save your Strava API credentials
• get_auth_url(redirect_uri): Get the authorization URL using stored credentials
• complete_strava_auth(auth_code): Complete authentication with authorization code
• check_auth_status(): Check if authentication is configured and tokens are available

Basic Activity Queries

• get_activities(limit): Get recent activities
• get_activities_by_range(start_date, end_date, limit): Get activities within a date range
• get_activity_by_id(activity_id): Get detailed information about a specific activity
• get_recent(days, limit): Get activities from the past X days
• get_runs_by_range(start_date, end_date, limit): Get running activities within a date range

Detailed Activity Analysis

• get_activity_streams(activity_id, keys): Get time-series data (heart rate, pace, power, cadence, GPS, etc.)
• get_activity_laps(activity_id): Get laps/splits for analyzing pace consistency
• get_activity_zones(activity_id): Get heart rate and power zone data

Athlete Statistics

• get_athlete_stats(athlete_id): Get athlete statistics including YTD totals, PRs, and achievements

Training Analysis

• analyze_weekly(start_date, end_date): Analyze weekly training metrics
• analyze_monthly(year, month): Analyze monthly training with weekly breakdown
• find_long_runs(start_date, end_date, min_distance_km): Find long runs within a date range
• analyze_pace_trends(start_date, end_date): Analyze pace trends over time

Heart Rate Zone & Injury Prevention

• analyze_hr_zones(start_date, end_date): Analyze heart rate zone distribution (80/20 principle)
• analyze_training_load(start_date, end_date): Analyze training load and identify injury risk indicators
• analyze_hr_trends(start_date, end_date, reference_pace_min_per_km): Track heart rate trends to monitor fitness improvements
• analyze_recovery(start_date, end_date): Analyze recovery patterns including rest days and training stress distribution

Note: Dates should be provided in ISO format (YYYY-MM-DD).

Usage

Claude for Desktop

Update your claude_desktop_config.json:

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

{
    "mcpServers": {
        "strava": {
            "command": "uvx",
            "args": ["strava-training-mcp"],
            "env": {
                "STRAVA_CLIENT_ID": "YOUR_CLIENT_ID",
                "STRAVA_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
                "STRAVA_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
            }
        }
    }
}

Running Locally

# SSE transport (recommended for remote connections)
uv run src/server.py --transport sse --port 9186

# Streamable-http transport (stateless HTTP POST)
uv run src/server.py --transport streamable-http --port 9186

# stdio transport (default, for local use)
uv run src/server.py --transport stdio

Example Queries

Authentication

• "Check my Strava authentication status"
• "Save my Strava credentials: client_id=12345, client_secret=abc123"
• "Get the authorization URL for Strava OAuth"
• "Complete Strava authentication with code XYZ789"

Basic Queries

• "What are my recent activities?"
• "Show me my activities from last week"
• "What was my longest run in the past month?"
• "Get details about my latest run"

Marathon Training Analysis

• "Analyze my weekly training from last week"
• "Show me my long runs from the past month"
• "What's my pace trend over the last 3 months?"
• "Analyze my training for January 2024"

Heart Rate Zone & Injury Prevention

• "Analyze my heart rate zones for the past month"
• "Check my training load and injury risk for the last 4 weeks"
• "Show me my heart rate trends over the past 3 months"
• "Analyze my recovery patterns - am I getting enough rest?"

Activity Data Format

The server returns activity data with consistent field names and units:

Development

Project Structure

strava-training-mcp/
├── src/
│   ├── server.py      # Main MCP server implementation
│   ├── client.py      # Strava API client wrapper
│   ├── tools.py       # MCP tool definitions
│   └── auth.py        # Authentication utilities
├── README.md
├── QUICK_START.md
├── AUTHENTICATION.md
├── STEP_BY_STEP_AUTH.md
└── pyproject.toml

Running Tests

# Run linting
uv run ruff check src/

# Type checking
uv run mypy src/

Authentication

The MCP server includes built-in authentication tools. See AUTHENTICATION.md for detailed instructions.

Quick Authentication

1. Get your Client ID and Client Secret from Strava API Settings
2. Use the MCP tool: get_strava_auth_token(client_id, client_secret, auth_code)
3. Restart the server

For step-by-step instructions, see STEP_BY_STEP_AUTH.md.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

This project is inspired by and builds upon the excellent work from tomekkorbak/strava-mcp-server. The original project provided the foundation and inspiration for this enhanced version, which adds comprehensive training analysis features, improved authentication flow, and marathon-specific tools.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.