A Model Context Protocol (MCP) server for interacting with the Wahoo Cloud API, focusing on reading workout information.
- Workouts: List workouts with pagination and date filtering, get detailed workout information
- Routes: List and retrieve saved cycling/running routes
- Training Plans: Access and create training plans in your Wahoo account
- Power Zones: View power zone configurations for different workout types
- OAuth 2.0 Authentication: Secure authentication with automatic token refresh
- Comprehensive workout type support: 72 different workout types with location and family categorization
- Async/await implementation: High-performance async operations using httpx
- Automatic token management: Tokens are refreshed automatically when they expire
First, install uv if you haven't already:
curl -LsSf https://astral.sh/uv/install.sh | shThen install the project dependencies:
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
uv pip install -e .For development:
uv pip install -e ".[dev]"If you prefer using pip:
python3.13 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e .For development:
pip install -e ".[dev]"-
Register your application at Wahoo's Developer Portal to get a Client ID and Client Secret.
-
Create a
.envfile from the example:cp .env.example .env
Then edit
.envand add your credentials:WAHOO_CLIENT_ID=your_client_id_here WAHOO_CLIENT_SECRET=your_client_secret_here
-
Set the token file path in your
.envfile:WAHOO_TOKEN_FILE=token.json
-
Use the authentication helper:
make auth # or uv run python src/auth.pyThis will:
- Use credentials from
.env(or prompt if not set) - Open a browser for OAuth authentication
- Receive the callback: with an
https://localhost/...redirect URI (Wahoo requires https), paste the redirected URL from the browser's address bar into the terminal; otherwise a local callback server receives it - Check the OAuth
state, and use the client secret (confidential app) or PKCE (public app, no secret set), never both - Save your tokens to the file specified by
WAHOO_TOKEN_FILE - Tokens will be automatically refreshed when needed
- Use credentials from
The auth server can be configured via environment variables:
Server Configuration:
WAHOO_AUTH_HOST: Auth server bind address (default:localhost)WAHOO_AUTH_PORT: Auth server port (default:8080)
Redirect URL Configuration:
WAHOO_REDIRECT_HOST: OAuth callback host (default: usesWAHOO_AUTH_HOST)WAHOO_REDIRECT_PORT: OAuth callback port (default: usesWAHOO_AUTH_PORT)WAHOO_REDIRECT_SCHEME: URL scheme -httporhttps(default:http)
Credentials:
WAHOO_CLIENT_ID: Your Wahoo Client IDWAHOO_CLIENT_SECRET: Your Wahoo Client SecretWAHOO_TOKEN_FILE: Path to store OAuth tokens (required)
Plans and scheduling:
WAHOO_FTP: FTP in watts for plan headers andpercent_ftptargets. If unset, the FTP is read from your Wahoo power zones.WAHOO_TIMEZONE: Timezone for start times without an offset and for the 6-day sync window (default:Europe/Berlin)
Scopes: the server requests workouts_write to schedule workouts. Tokens created before this change lack it: run make auth again.
Example Configurations:
-
Local Development (default):
# Redirect URL will be: http://localhost:8080/callback -
Using ngrok:
WAHOO_AUTH_HOST=localhost WAHOO_AUTH_PORT=8080 WAHOO_REDIRECT_HOST=your-app.ngrok.io WAHOO_REDIRECT_PORT=443 WAHOO_REDIRECT_SCHEME=https # Redirect URL will be: https://your-app.ngrok.io:443/callback
Note: When registering your app with Wahoo, use the redirect URL that matches your configuration.
uv run python -m src.serverOr if you've activated the virtual environment:
python -m src.serverAdd the following to your Claude Desktop configuration file:
Configuration file location:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Example configuration:
{
"mcpServers": {
"wahoo": {
"type": "stdio",
"command": "/path/to/uv",
"args": [
"--project",
"/path/to/wahoo-mcp",
"run",
"python",
"-m",
"src.server"
],
"env": {
"WAHOO_TOKEN_FILE": "/path/to/wahoo-mcp/token.json"
}
}
}
}Make sure to replace /path/to/ with your actual paths.
List workouts from your Wahoo account.
Parameters:
page(optional): Page number (default: 1)per_page(optional): Number of items per page (default: 30)start_date(optional): Filter workouts created after this date (ISO 8601 format)end_date(optional): Filter workouts created before this date (ISO 8601 format)
Example:
Use the list_workouts tool to show my recent workouts
Get detailed information about a specific workout.
Parameters:
workout_id(required): The ID of the workout to retrieve
Example:
Use the get_workout tool to get details for workout ID 12345
List routes from your Wahoo account.
Parameters:
external_id(optional): Filter routes by external ID
Example:
Use the list_routes tool to show my saved routes
Get detailed information about a specific route.
Parameters:
route_id(required): The ID of the route to retrieve
Example:
Use the get_route tool to get details for route ID 456
List training plans from your Wahoo account.
Parameters:
external_id(optional): Filter plans by external ID
Example:
Use the list_plans tool to show my training plans
Get detailed information about a specific plan.
Parameters:
plan_id(required): The ID of the plan to retrieve
Example:
Use the get_plan tool to get details for plan ID 789
List power zones from your Wahoo account.
Parameters: None
Example:
Use the list_power_zones tool to show my power zones
Get detailed information about a specific power zone.
Parameters:
power_zone_id(required): The ID of the power zone to retrieve
Example:
Use the get_power_zone tool to get details for power zone ID 321
Create a training plan in your Wahoo account, or replace the plan with the same external_id (GET /v1/plans?external_id= then PUT, otherwise POST). Deleted plans that Wahoo still lists with deleted=true are ignored.
Parameters:
plan(required): Complete workout plan structure containing:name(required): Name of the workout plandescription(optional): Description of the workoutintervals(required): List of workout intervals, each containing:duration(required): Duration in secondstargets(required): List of targets. Usewattsfor absolute power (recommended) orpercent_ftpwith a fraction (e.g.0.95), which is converted to watts. Also: hr, rpm, rpe, speed and the Wahoo relative types ftp, map, ac, nm. Each target needstarget_valueortarget_min+target_max.name(optional): Name/description of the intervalinterval_type(optional): Type (work, rest, warmup, cooldown, tempo, threshold, recovery, active, or Wahoo types: wu, cd, lt, map, ac, nm, ftp, recover)
workout_type(optional): bike (indoor, default), bike_indoor, bike_outdoor, run (outdoor), run_outdoor, run_indoor. Sets the plan header family and location.ftp(optional): FTP in watts; defaults toWAHOO_FTPor your Wahoo power zonesestimated_duration(optional): Estimated total duration in secondsestimated_tss(optional): Estimated Training Stress Scoreauthor(optional): Author of the plan
external_id(required): Unique external ID for the planprovider_updated_at(required): External date/time the file was updated (ISO 8601 format)filename(optional): Name of the plan file
Unknown target or interval types are rejected instead of being silently converted.
Example:
Use the create_plan tool to create a new training plan with intervals for power and heart rate zones
Schedule a workout on your Wahoo calendar and attach a plan, so it shows up on the ELEMNT and KICKR.
Parameters:
name(required): Workout namestarts(required): ISO 8601 start time; without an offset it is read inWAHOO_TIMEZONEminutes(required): Planned duration in minutesplan_id(optional): Plan to attach (fromcreate_planorlist_plans)route_id(optional): Route to attachworkout_type_id(optional): defaults to 12 (indoor biking)workout_token(optional): stable identifier from your planner. If a workout with this token exists among the 50 latest-starting workouts, it is updated instead of duplicated; completed workouts are never overwritten. Generated if omitted (no update possible then).allow_outside_window(optional): Wahoo only syncs workouts starting today through 6 days ahead to devices. Other dates are rejected unless this istrue.
Example:
Create the plan "Test Z2 30 min" and schedule it for tomorrow at 18:00
Push one planner session in one step: converts % FTP to watts with your FTP, creates or replaces the plan and schedules or updates the workout. The ID pbp-<date>-<name> (e.g. pbp-2026-10-18-angels) is used as plan external_id and as workout_token, so pushing the same session again replaces it.
Parameters:
date(required):YYYY-MM-DD, today through 6 days aheadtime(required): local start timeHH:MMinWAHOO_TIMEZONEname(required): session namesteps(required): list of steps, each withminutesorsecondsand one target:percent_ftp(fraction, e.g.0.65),percent_ftp_min+percent_ftp_max, orwatts. No target means a free ride (RPE 1-10). Optionalnameandtype(warmup, active, rest, cooldown, ...). A repeat block is{"repeat": 4, "steps": [...]}.description,session_id,workout_type,workout_type_id,ftp,allow_outside_window(optional)
Example:
{
"date": "2026-10-18", "time": "18:00", "name": "Angels",
"steps": [
{"name": "Einfahren", "minutes": 10, "percent_ftp": 0.55, "type": "warmup"},
{"repeat": 4, "steps": [
{"name": "Schwelle", "minutes": 8, "percent_ftp": 0.9},
{"name": "Locker", "minutes": 4, "percent_ftp": 0.5, "type": "rest"}
]},
{"name": "Ausfahren", "minutes": 10, "type": "cooldown"}
]
}The reply lists the absolute watts sent to Wahoo. All validation (window, step format, % FTP as fraction) happens before the first API request. A push costs about 4 requests.
create_plan accepts repeat blocks as well: an interval with repeat and nested intervals instead of duration and targets.
Delete a scheduled workout by workout_id or workout_token. Completed workouts (with a summary) are only deleted with force: true. A workout that is already gone is not an error.
Delete a plan by plan_id or external_id. Linked workouts are kept without plan. Wahoo keeps the deleted plan's external_id listed, so re-create it under a new external_id.
Sandbox apps may send 25 requests per 5 minutes, 100 per hour and 250 per day. On HTTP 429 the server waits up to 60 s (Retry-After / X-RateLimit-Reset) and retries once, otherwise it reports when to try again. A replacing push costs about 4 requests (plan lookup, plan PUT, workout lookup, workout PUT).
Status: tested locally (HTTP transport, OAuth flow, live Wahoo call); not yet deployed on the NAS.
To use the server from claude.ai connectors or scheduled Claude runs, run it as a remote MCP server with Streamable HTTP at /mcp:
uv run python -m src.http_app| Variable | Purpose |
|---|---|
WAHOO_PUBLIC_URL |
Public HTTPS base URL, e.g. https://wahoo.example.com; the connector URL is <WAHOO_PUBLIC_URL>/mcp |
WAHOO_OAUTH_PASSWORD |
Enables OAuth 2.1 with Dynamic Client Registration for claude.ai connectors. When Claude connects, you enter this password on the server's /login page (at least 12 characters) |
WAHOO_MCP_TOKEN |
Static bearer token (at least 32 characters, e.g. openssl rand -hex 32), e.g. for claude mcp add --transport http … --header "Authorization: Bearer …" |
WAHOO_OAUTH_REDIRECT_ALLOWLIST |
Redirect URIs allowed to register; default: https://claude.ai/api/mcp/auth_callback and loopback for Claude Code |
WAHOO_OAUTH_STATE_FILE |
OAuth clients and token hashes; default: next to WAHOO_TOKEN_FILE |
WAHOO_HTTP_HOST / WAHOO_HTTP_PORT |
Bind address, default 0.0.0.0:8000 |
WAHOO_ALLOW_NO_AUTH=1 |
Run without access control (local tests only) |
The server refuses to start without WAHOO_OAUTH_PASSWORD or WAHOO_MCP_TOKEN. Access tokens are stored only as SHA-256 hashes, and refresh tokens rotate on every use. After 5 wrong passwords within 15 minutes, the login locks. GET /health needs no token.
Docker / Synology: docker-compose.yml builds the image, mounts ./data for token.json and the OAuth state, and has an optional Cloudflare Tunnel service (docker compose --profile tunnel up -d, CLOUDFLARE_TUNNEL_TOKEN in .env). Copy the token.json from make auth to ./data/. Use only one copy: every Wahoo token refresh invalidates the previous refresh token, so the Mac and the NAS must not refresh in parallel.
uv run pytestOr if you've activated the virtual environment:
pytestwahoo-mcp/
├── src/
│ ├── __init__.py
│ ├── server.py # Main MCP server implementation
│ ├── auth.py # OAuth authentication helper
│ ├── token_store.py # Token storage and refresh logic
│ └── models.py # Pydantic models for API data structures
├── tests/
│ ├── __init__.py
│ ├── test_server.py # Server test suite
│ └── test_token_store.py # Token store tests
├── pyproject.toml # Project configuration
└── README.md # This file
The server implements the following Wahoo Cloud API endpoints:
Workouts:
GET /v1/workouts- List workouts with pagination and date filteringGET /v1/workouts/{id}- Get detailed workout information
Routes:
GET /v1/routes- List saved routesGET /v1/routes/{id}- Get route details including GPS data
Training Plans:
GET /v1/plans- List training plansGET /v1/plans/{id}- Get plan detailsPOST /v1/plans- Create a new training plan
Power Zones:
GET /v1/power_zones- List power zone configurationsGET /v1/power_zones/{id}- Get specific power zone details
For full API documentation, see Wahoo Cloud API.
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.