# Strava Training MCP
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/release/python-3120/)
A comprehensive [Model Context Protocol](https://modelcontextprotocol.io/introduction) (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)
```bash
# 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
```bash
pip install strava-training-mcp
```
## Quick Start
1. **Get Strava API credentials** from [Strava API Settings](https://www.strava.com/settings/api)
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](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`
```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
```bash
# 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:
| Field | Description | Unit |
|-------|-------------|------|
| `id` | Activity ID | - |
| `name` | Activity name | - |
| `sport_type` | Type of sport | - |
| `start_date` | Start date and time | ISO 8601 |
| `distance_metres` | Distance | meters |
| `elapsed_time_seconds` | Total elapsed time | seconds |
| `moving_time_seconds` | Moving time | seconds |
| `average_speed_mps` | Average speed | meters per second |
| `max_speed_mps` | Maximum speed | meters per second |
| `average_cadence_rpm` | Average cadence | revolutions per minute |
| `average_heartrate_bpm` | Average heart rate | beats per minute |
| `max_heartrate_bpm` | Maximum heart rate | beats per minute |
| `average_watts` | Average power | watts |
| `weighted_average_watts` | Weighted average power | watts |
| `kilojoules` | Energy output | kilojoules |
| `total_elevation_gain_metres` | Total elevation gain | meters |
| `elev_high_metres` | Highest elevation | meters |
| `elev_low_metres` | Lowest elevation | meters |
| `calories` | Calories burned | kcal |
| `workout_type` | Workout type (0=default, 1=race, 2=long run, 3=workout) | - |
| `suffer_score` | Perceived exertion score | - |
| `start_latlng` | Start coordinates | [lat, lng] |
| `end_latlng` | End coordinates | [lat, lng] |
## 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
```bash
# 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](AUTHENTICATION.md) for detailed instructions.
### Quick Authentication
1. Get your Client ID and Client Secret from [Strava API Settings](https://www.strava.com/settings/api)
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](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](https://github.com/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.
