Wahoo MCP Server

Wahoo MCP Server

A Model Context Protocol (MCP) server for interacting with the Wahoo Cloud API, focusing on reading workout information.

Features

• 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

Installation

Using uv (recommended)

First, install uv if you haven't already:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then 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]"

Using pip (alternative)

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]"

Configuration

Getting an Access Token

1. Register your application at Wahoo's Developer Portal to get a Client ID and Client Secret.

2. Create a .env file from the example:

   cp .env.example .env
   

   Then edit .env and add your credentials:

   WAHOO_CLIENT_ID=your_client_id_here
   WAHOO_CLIENT_SECRET=your_client_secret_here
   

3. Set the token file path in your .env file:

   WAHOO_TOKEN_FILE=token.json
   

4. Use the authentication helper:

   make auth
   # or
   uv run python src/auth.py
   

   This will:

   • Use credentials from .env (or prompt if not set)
   • Open a browser for OAuth authentication
   • Start a local server to receive the callback
   • Save your tokens to the file specified by WAHOO_TOKEN_FILE
   • Tokens will be automatically refreshed when needed

Configuration Options

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: uses WAHOO_AUTH_HOST)
• WAHOO_REDIRECT_PORT: OAuth callback port (default: uses WAHOO_AUTH_PORT)
• WAHOO_REDIRECT_SCHEME: URL scheme - http or https (default: http)

Credentials:

• WAHOO_CLIENT_ID: Your Wahoo Client ID
• WAHOO_CLIENT_SECRET: Your Wahoo Client Secret
• WAHOO_TOKEN_FILE: Path to store OAuth tokens (required)

Example Configurations:

1. Local Development (default):

   # Redirect URL will be: http://localhost:8080/callback
   

2. 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.

Usage

Running the MCP Server

uv run python -m src.server

Or if you've activated the virtual environment:

python -m src.server

Using with Claude Desktop

Add 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.

Available Tools

list_workouts

List workouts from your Wahoo account.

Parameters:

• page (optional): Pa