trainingpeaks-mcp

TrainingPeaks MCP Server is an open-source server based on the Model Context Protocol (MCP), used to connect TrainingPeaks with AI assistants such as Claude Desktop, Claude Code, and Cowork. It does not rely on the official TrainingPeaks API (which requires approval), but instead uses secure Cookie authentication, so any account user can complete configuration within a few minutes.

Main capabilities

• Query training: query training records, training details, and training comments in natural language.
• Fitness metric analysis: query fitness data such as CTL/ATL/TSB, and view weekly TSS and ATP goal progress.
• Power PRs and trends: compare power personal records, for example comparing this year's and last year's FTP progress.
• Structured workout creation: automatically generate interval structures based on the conversation, and the server automatically calculates duration, IF, and TSS, for example "build a 4x8 minute threshold workout with a warm-up and cool-down".
• Calendar management: create, update, and delete workouts, events, notes, equipment, and settings; supports all-day plans (YYYY-MM-DD) and specified start times (YYYY-MM-DDTHH:MM:SS).
• Copying and scheduling: copy last week's long ride to this Saturday, or schedule a flexibility workout for a certain day.
• Health data logging: record weight, sleep duration, and more.
• Zones and thresholds: set FTP, LTHR, and threshold pace and update power zones; zones are located by activity type, and zone bands are recalculated using TrainingPeaks' own zone calculator, respecting the athlete's calculation method (such as %LTHR, Karvonen, Andy Coggan, etc.).
• Other: workout library, strength training, athlete groups under coach accounts, multi-week training plans, event calendar, and number of weeks to a distance A-priority event.

How to use

Authentication supports three methods:

1. Automatically extract Cookies from the browser: you must already be logged in to TrainingPeaks; on macOS, a Keychain or Full Disk Access permission prompt may appear, which is normal.
2. Manually enter Cookies: log in to app.trainingpeaks.com, open Developer Tools (F12) → Application → Cookies, find Production_tpAuth and copy its value, then runtp-mcp auth and paste it.
3. Environment variables (headless servers, containers, CI): set TP_AUTH_COOKIE to the value of Production_tpAuth, or add it in the env block of the MCP client configuration. This method is a supported first-class authentication method and is checked before the system Keychain and encrypted file.

Installation can be completed automatically through Claude Code (after pasting the prompt, Claude handles the installation and guides authentication), or configured manually. After obtaining the configuration snippet, edit claude_desktop_config.json (macOS path ~/Library/Application Support/Claude/claude_desktop_config.json, Windows path %APPDATA%\Claude\claude_desktop_config.json), paste it into mcpServers, and restart Claude Desktop.

Security design

• Cookies are never stored in plaintext; the encrypted file fallback uses AES-256-GCM authenticated encryption, a PBKDF2-derived key (600,000 iterations), and a machine-specific salt.
• The AI assistant (Claude) can never see the Cookie value: tool results scrub keys containing cookie, token, auth, credential, password, or secret; the repr of BrowserCookieResult and CredentialResult only shows cookie=<present>; exception messages use only the exception type name; Cookie values are never written to logs.
• Browser Cookie extraction only accesses .trainingpeaks.com (the domain is hardcoded, Claude cannot modify it through tool parameters, and the only parameter is browser).
• Only stdio transport is used, with no HTTP server, no open ports, and no remote access.
• The authentication flow has two steps: the Cookie is exchanged for a short-lived OAuth access token (expires in 1 hour); the token is cached in memory and automatically refreshed before expiration; API calls use the Bearer token rather than the Cookie. When the session Cookie expires (usually after several weeks), you can Use tp_refresh_auth in Claude or re-run tp-mcp auth.
• v2.0 adds full calendar management write permissions, and all changes go through Pydantic validation; the server cannot access billing or payment information.
• The project is fully open source, and all code can be audited.

Structured training and tool calls

When creating and updating training, you can use a simplified structure object, or use a native structured_workout payload in the TrainingPeaks builder format; only one of the two can be used per call. When duration_minutes and tss_planned are omitted, they are automatically derived from the structure; if explicitly passed in, they override the derived values. Training that already has a native structure will be returned as structured_workout in tp_get_workout. Training comments are obtained via tp_get_workout()["workout_comments"] or tp_get_workout_comments().

MCP Apps inline charts

On clients that support the MCP Apps extension (2026-07-28 specification), some tools can render interactive UI inline in the conversation while also returning the regular text payload; other clients behave unchanged, and the text answer is always complete. As of July 2026, Claude clients still connect to local stdio servers via the pre-2026 protocol, so the app is ready but will not render, and the tool text output is unaffected.

Limitations

• Interval sets based on the test (Distance/Time) method cannot have thresholds set directly, because no stable value exists; the tool will detect this and return TEST_BASED_METHOD (without writing anything), and such interval sets need to be configured via a test in the TrainingPeaks UI.
• Manual configuration is required, and after the Cookie session expires, re-authentication or refresh is required.
• When using TP_AUTH_COOKIE in a headless environment, note that environment variables can be read by processes under the same user and by docker inspect; it is recommended to inject it from a secret manager, and never hardcode it into a Dockerfile, compose file, or commit it to git.
• For desktop environments, keychain/encrypted file storage is recommended (options A, B); TP_AUTH_COOKIE is used for headless and containerscenarios.

The remaining specific installation commands, client configuration examples, and code details are subject to the actual contents of the project repository; features, pricing, platforms, or effects not provided in the text are not yet available.