Mcpstrava

🏃 Strava MCP Server

A Model Context Protocol (MCP) server that connects Claude to your Strava account — ask in natural language to analyze your training, predict race times, compute training loads, or generate a full periodized training plan.

✨ Features

• 🧰 13 tools across 5 categories: auth, activities, analysis, prediction, planning
• 🔐 OAuth2 flow with an automatic local callback server — no manual code copying
• 🏅 VDOT-based training paces (Jack Daniels' Running Formula)
• 📈 CTL / ATL / TSB training load metrics — Chronic & Acute Training Load, Training Stress Balance
• ⏱️ Race time predictions via the Riegel formula
• 📅 Full periodized training plans (Base → Build → Peak → Taper) with race-specific logic

📋 Requirements

🚀 Quick Start

1. Create a Strava API application

Go to strava.com/settings/api and create an application.

• Authorization Callback Domain: localhost

💡 Note down your Client ID and Client Secret — you'll need them in the next steps.

2. Configure environment variables

cp .env.example .env

Edit .env:

STRAVA_CLIENT_ID=your_client_id
STRAVA_CLIENT_SECRET=your_client_secret
STRAVA_REDIRECT_URI=http://localhost:8080/callback
TOKENS_FILE_PATH=./tokens.json

3. Build

npm install
npm run build

4. Configure Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "strava": {
      "command": "node",
      "args": ["C:/path/to/McpStrava/dist/index.js"],
      "env": {
        "STRAVA_CLIENT_ID": "your_client_id",
        "STRAVA_CLIENT_SECRET": "your_client_secret",
        "TOKENS_FILE_PATH": "C:/path/to/McpStrava/tokens.json"
      }
    }
  }
}

💡 Tip

You can use either .env or the env block in the Claude Desktop config — both work.

5. Authenticate

Restart Claude Desktop, then in a conversation:

1. Call strava_get_auth_url — Claude will return a URL
2. Open the URL in your browser and authorize the app on Strava
3. The page will show "✓ Authentification réussie !" and tokens are saved automatically

🛠️ Available Tools

🔐 Authentication

🏃 Activities

📊 Analysis

⏱️ Prediction

📅 Training Planning

📈 Training Plan Details

Phases

🧮 How volume is calculated

1. Starting volume — blend of your 4-week average km and CTL-derived weekly km estimate (robust to injury breaks)
2. Peak volume — 1.4× current, with race-specific minimums (5K: 40 km, 10K: 50 km, Half: 60 km, Marathon: 80 km)
3. Weekly progression — capped at +10% per week to prevent injury
4. Recovery weeks — automatic every 4th week within each phase (volume × 0.8)

🎯 Race-specific logic

• Marathon (Build & Peak): Long runs include a marathon-pace section (~45% of the run at race pace)
• Taper depth: 5K tapers to 80% of peak volume, Marathon to 40% — shorter races need less recovery
• Intervals: 6 × 1000 m for 5K/10K, 5 × 1000 m for Half/Marathon

🏅 VDOT & pace zones

Based on Jack Daniels' Running Formula. Zones computed as a fraction of VDOT:

👥 Generating Plans for Friends (Manual Mode)

strava_generate_training_plan supports a manual mode that bypasses Strava entirely. Pass current_weekly_km and goal_time together and no Strava account is needed — useful for generating plans for friends from your own Claude Desktop.

Required parameters

Example prompts

Generate a marathon plan for my friend — he runs 55 km per week and is targeting 3h45, the race is on October 18, 2026

My friend wants to run a half marathon in 1h50 on 2026-09-14, she does about 40 km per week

💡 How it works

When both current_weekly_km and goal_time are provided, the tool skips all Strava API calls. The resume in the response will include source_volume: "Fourni manuellement" to confirm which mode was used.

Mode comparison

🧑💻 Development

# Watch mode (no build step needed)
npm run dev

# Build TypeScript
npm run build

# Run built server
npm start

# Clean build artifacts
npm run clean

📁 Project structure

src/
├── index.ts                  # MCP server entry point
├── config.ts                 # Env vars, Strava constants, race distances
├── types.ts                  # Shared TypeScript interfaces
├── auth/
│   ├── oauth.ts              # OAuth2 URL builder, token exchange
│   ├── tokenStore.ts         # Load/save tokens.json, expiry check
│   ├── callbackServer.ts     # Local HTTP server for OAuth redirect
│   └── authTools.ts          # MCP auth tools
├── strava/
│   ├── client.ts             # Axios instance with auto token refresh
│   ├── activities.ts         # Strava activities API
│   ├── athlete.ts            # Strava athlete/stats API
│   └── activityTools.ts      # MCP activity tools
├── analytics/
│   ├── metrics.ts            # Weekly stats, pace zones, consistency score
│   ├── trainingLoad.ts       # TRIMP, CTL/ATL/TSB computation
│   └── analysisTools.ts      # MCP analysis tools
├── prediction/
│   ├── riegel.ts             # Riegel race time prediction formula
│   ├── vdot.ts               # VDOT computation, training paces, race equivalents
│   └── predictionTools.ts    # MCP prediction tools
└── planning/
    ├── workouts.ts           # Workout templates and distance bounds
    ├── plan.ts               # Plan generation, phase allocation, VDOT estimation
    └── planTools.ts          # MCP planning tools

🔑 Tokens

tokens.json stores your Strava access and refresh tokens. It is in .gitignore — never commit it. Tokens are refreshed automatically when they expire (Strava access tokens last 6 hours).

💬 Example Prompts

Strava mode (your own account)

Analyze my last 8 weeks of training

What would my marathon time be if I run a 10K in 45 min?

Generate me a training plan for a half marathon on 2026-09-20

Compute my current training load and tell me whether I'm fresh for a race this weekend

Show me my pace distribution over the last 4 weeks

Manual mode (friends / no Strava)

Generate a marathon plan for my friend — he runs 55 km per week and is targeting 3h45, the race is on October 18, 2026

My friend wants to run a half marathon in 1h50 on September 14, 2026, she does 40 km per week

📄 License

MIT