trainingpeaks-mcp

An MCP (Model Context Protocol) server for accessing your TrainingPeaks training data. Works with Claude Desktop, ChatGPT, and other MCP-compatible clients.

Features

• 20 tools for accessing workouts, strength workouts, fitness metrics, peaks/PRs, power analysis, aerobic decoupling, workout plan compliance, ZWO workout generation, files, cache management, and date resolution
• FIT file caching: Downloaded FIT files are cached to disk (~/.trainingpeaks-mcp/cache/fit/) — eliminates redundant downloads across sessions
• Dual transport: stdio for Claude Desktop, HTTP for ChatGPT
• FIT file parsing: Extract structured data from downloaded FIT files
• Also usable as a standalone TypeScript library

Quick Start

One-Click Install (Claude Desktop)

1. Download the latest .mcpb file from Releases
2. Double-click the .mcpb file — Claude Desktop will open and prompt you to install
3. Enter your TrainingPeaks credentials when prompted

That's it — no Node.js installation required. Claude Desktop bundles its own runtime.

Manual Configuration (Claude Desktop)

Requires Node.js 20+. Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "trainingpeaks": {
      "command": "npx",
      "args": ["trainingpeaks-mcp"],
      "env": {
        "TP_USERNAME": "[email protected]",
        "TP_PASSWORD": "your-password"
      }
    }
  }
}

Restart Claude Desktop. You can now ask Claude about your training data!

ChatGPT (via HTTP)

Requires Node.js 20+.

1. Clone and install:

   git clone https://github.com/robertgregorywest/trainingpeaks-mcp.git
   cd trainingpeaks-mcp
   npm install

2. Create .env file with your credentials:

   cp .env.example .env
   # Edit .env with your TrainingPeaks credentials

3. Build and start the HTTP server:

   npm run build
   npm run start:http

   You should see: TrainingPeaks MCP HTTP server running on port 3000

4. Install ngrok (if not already installed):

   macOS (Homebrew):

   brew install ngrok

   Windows (Chocolatey):

   choco install ngrok

   Or download directly from: https://ngrok.com/download

5. Create a free ngrok account and get your auth token:

   • Sign up at https://dashboard.ngrok.com/signup
   • Copy your auth token from https://dashboard.ngrok.com/get-started/your-authtoken
   • Configure ngrok with your token:

     ngrok config add-authtoken YOUR_AUTH_TOKEN

6. Start ngrok to expose your local server (in a new terminal):

   ngrok http 3000

   ngrok will display output like:

   Forwarding   https://abc123.ngrok-free.app -> http://localhost:3000

   Copy the https://...ngrok-free.app URL.

7. Add the MCP connector in ChatGPT:

   • Go to ChatGPT Settings → Connectors → Add Connector
   • Enter your ngrok URL with /mcp path: https://abc123.ngrok-free.app/mcp
   • Save the connector

8. Test by asking ChatGPT about your TrainingPeaks data!

Available Tools

| Tool | Description | | -------------------------- | ------------------------------------------------------------------------------------------------------------------- | | get_user | Get user profile including athlete ID | | get_athlete_id | Get just the athlete ID | | get_workouts | List workouts in a date range | | get_workout | Get single workout summary | | get_workout_details | Get workout with full metrics, intervals, laps, zones | | search_workouts | Search workouts by title (case-insensitive) within a number of days | | compare_intervals | Compare laps/intervals side-by-side across workouts with power/duration filters | | get_strength_workouts | Get strength workouts in a date range (sets, blocks, exercises, compliance) | | parse_fit_file | Parse FIT file and extract structured data | | get_fitness_data | Get CTL/ATL/TSB for date range | | get_current_fitness | Get today's fitness metrics | | get_peaks | Get peaks for specific sport and type | | get_workout_peaks | Get PRs from specific workout | | get_best_power | Compute best power from raw FIT file for arbitrary durations (e.g., 3min, 8min, 45min) | | get_power_duration_curve | Build a power-duration curve across cycling workouts in a date range | | get_aerobic_decoupling | Calculate aerobic decoupling (Pw:Hr) from a workout — measures cardiac drift | | assess_compliance | Assess workout plan compliance — compares prescribed plan against actual activity with per-step and summary metrics | | build_zwo_workout | Build a Zwift .zwo workout file from structured segments (warmup, intervals, steady, ramp, cooldown, freeride) | | clear_fit_cache | Clear all cached FIT files downloaded from TrainingPeaks | | get_current_date | Get current date in ISO, US, EU, or custom format |

Example Prompts

• "What workouts did I do last week?"
• "Show me my current fitness (CTL, ATL, TSB)"
• "What are my best 5-minute power efforts?"
• "Get details for my most recent ride including heart rate zones"
• "Download and parse the FIT file from yesterday's ride"
• "Search for all my tempo workouts in the last 30 days"
• "Compare the intervals across my last 3 threshold rides"
• "What's my best 3-minute and 8-minute power from yesterday's ride?"
• "Build my power-duration curve for the last 6 weeks"
• "What's the aerobic decoupling for my last long ride?"
• "How well did I follow the plan for yesterday's ride?"
• "Create a 5x5 VO2max workout at 300W with 50% FTP recovery for Zwift"
• "Build me a sweet spot session with 3x10min at 220W"
• "What is today's date?"

Environment Variables

Create a .env file from the example:

cp .env.example .env

Then edit .env with your TrainingPeaks credentials:

[email protected]
TP_PASSWORD=your-password

| Variable | Description | Optional | | ------------------------- | ------------------------------------------------------------------------- | -------- | | TP_USERNAME | TrainingPeaks email address | No | | TP_PASSWORD | TrainingPeaks password | No | | PORT | HTTP server port (default: 3000) | Yes | | TP_TEST_BIKE_WORKOUT_ID | Bike workout ID with FIT file, power, and HR data (for integration tests) | Yes |

Library Usage

You can also use this package as a standalone TypeScript library:

import { createClient } from "trainingpeaks-mcp";

const client = createClient();

// Get workouts for a date range
const workouts = await client.getWorkouts("2024-01-01", "2024-12-31");

// Get workout details with metrics
const details = await client.getWorkoutDetails(workouts[0].workoutId);
console.log(details.metrics);

// Get current fitness
const fitness = await client.getCurrentFitness();
console.log(`CTL: ${fitness.ctl}, ATL: ${fitness.atl}, TSB: ${fitness.tsb}`);

// Build a power-duration curve from the last 6 weeks of rides
const curve = await client.getPowerDurationCurve({
  startDate: "2024-11-01",
  endDate: "2024-12-15",
});
console.log(curve.curve.map((p) => `${p.durationLabel}: ${p.bestPowerWatts}W`));

// Aerobic decoupling analysis
const decoupling = await client.getAerobicDecoupling(workouts[0].workoutId);
console.log(
  `Decoupling: ${decoupling.decouplingPercent}% — ${decoupling.interpretation}`,
);

// Workout plan compliance assessment
const compliance = await client.assessCompliance(workouts[0].workoutId);
console.log(
  `Plan compliance: ${compliance.overallCompliance.powerComplianceAvg}%`,
);

// Clean up when done
await client.close();

Development

npm run build        # Compile TypeScript
npm run lint         # Run ESLint
npm run test         # Run unit tests
npm run typecheck    # Type-check without emitting

Integration Tests

Integration tests make real API calls to TrainingPeaks to verify all endpoints work correctly.

Prerequisites:

1. Create .env file with your TrainingPeaks credentials (see Environment Variables)

Run integration tests:

npm run test:integration

What's tested:

• User API: getUser, getAthleteId
• Workouts API: getWorkouts, getWorkout, getWorkoutDetails
• Fitness API: getCurrentFitness, getFitnessData
• Peaks API: getPeaks, getWorkoutPeaks
• Files API: downloadActivityFile

Tests are skipped automatically if credentials are not available.

How It Works

This library uses Playwright to automate browser login to TrainingPeaks, capturing the authentication token from API requests. The token is then used for subsequent API calls.

License

MIT