Trainingpeaks MCP

🚀 TrainingPeaks MCP Server

Connect TrainingPeaks to Claude and other AI assistants via the Model Context Protocol (MCP). Query your workouts, analyze training load, compare power data, and track fitness trends through natural conversation.

No API approval required. The official Training Peaks API is approval-gated, but this server uses secure cookie authentication that any user can set up in minutes. Your cookie is stored in your system keyring, never transmitted anywhere except to TrainingPeaks.

🚀 Quick Start

Connect TrainingPeaks to AI assistants like Claude using the Model Context Protocol (MCP). You can query workouts, analyze training loads, compare power data, and track fitness trends through natural conversations. No API approval is needed as it uses secure cookie authentication.

✨ Features

📦 Installation

Option A: Auto-Setup with Claude Code

If you have Claude Code, paste this prompt:

Set up the TrainingPeaks MCP server from https://github.com/JamsusMaximus/trainingpeaks-mcp - clone it, create a venv, install it, then walk me through getting my TrainingPeaks cookie from my browser and run tp-mcp auth. Finally, add it to my Claude Desktop config.

Claude will handle the installation and guide you through authentication step-by-step.

Option B: Manual Setup

Step 1: Install

git clone https://github.com/JamsusMaximus/trainingpeaks-mcp.git
cd trainingpeaks-mcp
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e .

Step 2: Authenticate

Option A: Auto-extract from browser (easiest) If you're logged into TrainingPeaks in your browser:

pip install tp-mcp[browser]  # One-time: install browser support
tp-mcp auth --from-browser chrome  # Or: firefox, safari, edge, auto

macOS note: You may see security prompts for Keychain or Full Disk Access. This is normal - browser cookies are encrypted and require permission to read.

Option B: Manual cookie entry

1. Log into app.trainingpeaks.com
2. Open DevTools (F12) → Application tab → Cookies
3. Find Production_tpAuth and copy its value
4. Run tp-mcp auth and paste when prompted

Other auth commands:

tp-mcp auth-status  # Check if authenticated
tp-mcp auth-clear   # Remove stored cookie

Step 3: Add to Claude Desktop

Run this to get your config snippet:

tp-mcp config

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows) and paste it inside mcpServers. Example with multiple servers:

{
  "mcpServers": {
    "some-other-server": {
      "command": "npx",
      "args": ["some-other-mcp"]
    },
    "trainingpeaks": {
      "command": "/Users/you/trainingpeaks-mcp/.venv/bin/tp-mcp",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop. You're ready to go!

💻 Usage Examples

Basic Usage

You can ask your AI assistant questions like:

• "Compare my FTP progression this year vs last year"
• "What was my TSS ramp rate in the 6 weeks before my best 20-min power?"
• "Am I ready to race? Show my form trend and recent workout quality"
• "Which days of the week do I typically train hardest?"
• "Find weeks where I exceeded 800 TSS and show what happened to my form after"

Advanced Usage

Here are some API usage examples:

tp_get_workouts

List workouts in a date range. Max 90 days per query.

{ "start_date": "2026-01-01", "end_date": "2026-01-07", "type": "completed" }

tp_get_workout

Get full details for one workout including power, HR, cadence, TSS.

{ "workout_id": "123456789" }

tp_analyze_workout

Get detailed workout analysis including metrics, zones, and lap data. Full time-series data is saved to a JSON file for further analysis.

{ "workout_id": "123456789" }

tp_create_workout

Create a planned workout on a given date.

{ "date": "2026-02-01", "sport": "Run", "title": "Easy 5K", "duration_minutes": 30 }

Sports: Bike, Run, Swim, Strength, DayOff, Other Optional fields: description (max 2000 chars), distance_km, tss_planned

tp_get_peaks

Get ranked personal records. Bike: power metrics. Run: pace/speed metrics.

{ "sport": "Bike", "pr_type": "power20min", "days": 365 }

Bike types: power5sec, power1min, power5min, power10min, power20min, power60min, power90min, hR5sec, hR1min, hR5min, hR10min, hR20min, hR60min, hR90min Run types: speed400Meter, speed800Meter, speed1K, speed1Mi, speed5K, speed5Mi, speed10K, speed10Mi, speedHalfMarathon, speedMarathon, speed50K, hR5sec, hR1min, hR5min, hR10min, hR20min, hR60min, hR90min

tp_get_fitness

Get training load metrics over time.

{ "days": 90 }

Alternatively, query a specific date range:

{ "start_date": "2025-01-01", "end_date": "2025-03-31" }

Returns daily CTL (chronic training load / fitness), ATL (acute training load / fatigue), and TSB (training stress balance / form).

tp_get_workout_prs

Get PRs set during a specific workout.

{ "workout_id": "123456789" }

📚 Documentation

What is MCP?

Model Context Protocol is an open standard for connecting AI assistants to external data sources. MCP servers expose tools that AI models can call to fetch real-time data, enabling assistants like Claude to access your Training Peaks account through natural language.

🔧 Technical Details

Security

TL;DR: Your cookie is encrypted on disk, exchanged for short-lived OAuth tokens, never shown to Claude, and only ever sent to TrainingPeaks. The server has no network ports.

This server is designed with defense-in-depth. Your TrainingPeaks session cookie is sensitive - it grants access to your training data - so we treat it accordingly.

Write access: tp_create_workout can create planned workouts. All other tools are read-only. The server cannot modify or delete existing workouts.

Cookie Storage

Your cookie is never stored in plaintext. The encrypted file fallback uses AES-256-GCM authenticated encryption with a PBKDF2-derived key (600,000 iterations) and a machine-specific salt.

Cookie Never Leaks to AI

The AI assistant (Claude) never sees your cookie value. Multiple layers ensure this:

1. Return value sanitization: Tool results are scrubbed for any keys containing cookie, token, auth, credential, password, or secret before being sent to Claude
2. Masked repr(): The BrowserCookieResult and CredentialResult classes override __repr__ to show cookie=<present> instead of the actual value
3. Sanitized exceptions: Error messages use only exception type names, never full messages that could contain data
4. No logging: Cookie values are never written to any log

Domain Hardcoding (Cannot Be Changed)

The browser cookie extraction only accesses .trainingpeaks.com:

# From src/tp_mcp/auth/browser.py - HARDCODED, not a parameter
cj = func(domain_name=".trainingpeaks.com")

Claude cannot modify this via tool parameters. The only parameter is browser (chrome/firefox/etc), not the domain. To change the domain would require modifying the source code.

Read-Only Access

This server provides limited write access to TrainingPeaks:

• ✅ Query workouts, fitness metrics, personal records
• ✅ Create planned workouts
• ❌ Cannot modify or delete existing workouts
• ❌ Cannot change account settings
• ❌ Cannot access billing or payment info

No Network Exposure

The MCP server uses stdio transport only - it communicates with Claude Desktop via stdin/stdout, not over the network. There is no HTTP server, no open ports, no remote access.

What This Server Cannot Do

Authentication Flow

The server uses a two-step authentication process:

1. Cookie → OAuth Token: Your stored cookie is exchanged for a short-lived OAuth access token (expires in 1 hour)
2. Automatic Refresh: Tokens are cached in memory and automatically refreshed before expiry

This means:

• You only need to authenticate once with tp-mcp auth
• API calls use proper Bearer token auth, not cookies
• If your session cookie expires (typically after several weeks), use tp_refresh_auth in Claude or run tp-mcp auth again

Development

pip install -e ".[dev]"
pytest tests/ -v
mypy src/
ruff check src/

📄 License

MIT