Skip to main content
Glama
armonge

Wahoo MCP Server

by armonge
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Wahoo MCP Server

CI codecov Python 3.13+ License: GPL v3

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

Related MCP server: concept2-mcp-server

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): 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_workout

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

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_route

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_plans

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_plan

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

List power zones from your Wahoo account.

Parameters: None

Example:

Use the list_power_zones tool to show my power zones

get_power_zone

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_plan

Create a new training plan in your Wahoo account.

Parameters:

  • plan (required): Complete workout plan structure containing:

    • name (required): Name of the workout plan

    • description (optional): Description of the workout

    • intervals (required): List of workout intervals, each containing:

      • duration (required): Duration in seconds

      • targets (required): List of targets (power, heart_rate, speed, pace, rpe, cadence)

      • name (optional): Name/description of the interval

      • interval_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): Type of workout (bike, run, swim) - defaults to "bike"

    • estimated_duration (optional): Estimated total duration in seconds

    • estimated_tss (optional): Estimated Training Stress Score

    • author (optional): Author of the plan

  • external_id (required): Unique external ID for the plan

  • provider_updated_at (required): External date/time the file was updated (ISO 8601 format)

  • filename (optional): Name of the plan file

Example:

Use the create_plan tool to create a new training plan with intervals for power and heart rate zones

Development

Running Tests

uv run pytest

Or if you've activated the virtual environment:

pytest

Project Structure

wahoo-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

API Reference

The server implements the following Wahoo Cloud API endpoints:

Workouts:

  • GET /v1/workouts - List workouts with pagination and date filtering

  • GET /v1/workouts/{id} - Get detailed workout information

Routes:

  • GET /v1/routes - List saved routes

  • GET /v1/routes/{id} - Get route details including GPS data

Training Plans:

  • GET /v1/plans - List training plans

  • GET /v1/plans/{id} - Get plan details

  • POST /v1/plans - Create a new training plan

Power Zones:

  • GET /v1/power_zones - List power zone configurations

  • GET /v1/power_zones/{id} - Get specific power zone details

For full API documentation, see Wahoo Cloud API.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Available Tools

9 tools
create_planC

Create a new plan in the user's library

ParametersJSON Schema
NameRequiredDescriptionDefault
planYesComplete workout plan structure
filenameNoName of the plan file
external_idYesUnique external ID for the plan
provider_updated_atYesExternal date/time the file was updated (ISO 8601 format)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states this is a creation operation but doesn't mention permissions required, whether it's idempotent, error conditions, or what happens on success (e.g., returns a plan ID). For a mutation tool with zero annotation coverage, this is inadequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero wasted words. It's appropriately sized and front-loaded with the essential information about what the tool does.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with complex nested parameters (4 params, 3 required, nested objects) and no annotations or output schema, the description is insufficient. It doesn't explain what constitutes a valid 'plan' structure, how to handle the 'external_id', or what the tool returns upon success.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description adds no additional parameter information beyond what's in the schema, which is acceptable given the comprehensive schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Create') and resource ('new plan in the user's library'), making the purpose immediately understandable. It doesn't differentiate from sibling tools like 'get_plan' or 'list_plans', but it's not misleading or tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'list_plans' or 'get_plan'. There's no mention of prerequisites, constraints, or typical use cases, leaving the agent to infer usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_planC

Get detailed information about a specific plan

ParametersJSON Schema
NameRequiredDescriptionDefault
plan_idYesThe ID of the plan to retrieve

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description should compensate. It only states 'get detailed information' but does not disclose that it is a read-only, idempotent operation, or what happens on error (e.g., invalid plan_id). The behavioral profile is under-specified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of 8 words, which is concise but too minimal. It lacks any structure (e.g., multiple sentences or bullet points) that could enhance readability while staying brief.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with one parameter and no output schema, the description is adequate but not complete. It does not hint at the return structure (e.g., includes exercises, duration) or any constraints. Given the low complexity, it meets the minimum viable level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with a description for the only parameter (plan_id). The tool description adds no extra meaning beyond what the schema already provides, which meets the baseline for a fully documented schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (get) and resource (plan). It is specific enough to distinguish from siblings like list_plans (listing) and create_workout (creation). However, it does not elaborate on what 'plan' means or how it differs from other 'get' tools like get_power_zone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidance is given. There is no mention of when to use this tool versus alternatives (e.g., list_plans for overview, or get_power_zone for specific data). The description omits prerequisites or context for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_power_zoneB

Get detailed information about a specific power zone

ParametersJSON Schema
NameRequiredDescriptionDefault
power_zone_idYesThe ID of the power zone to retrieve

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description bears full burden. It indicates a read operation ('Get') but does not explicitly state it is non-destructive or confirm safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no redundancy, front-loaded with the action. It is concise but could be more informative without losing brevity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple retrieval tool with one required parameter and no output schema, the description is minimally adequate but lacks usage guidance and behavioral details.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds no extra meaning to the parameter beyond what the schema already provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'Get detailed information about a specific power zone', which clearly indicates a retrieval operation for a single resource. It distinguishes from sibling list_power_zones by specifying 'specific'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit instructions on when to use this tool versus alternatives. The intended use is implied (when you have a specific power_zone_id), but no exclusions or alternatives are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_routeB

Get detailed information about a specific route

ParametersJSON Schema
NameRequiredDescriptionDefault
route_idYesThe ID of the route to retrieve

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('Get') but does not reveal whether this is a read-only operation, if it requires authentication, has rate limits, or what the output format entails. For a tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded and wastes no space, making it highly concise and well-structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter, no output schema, no annotations), the description is minimally adequate but lacks depth. It does not explain return values or behavioral traits, which are crucial for a tool with no structured output or safety hints, leaving gaps in completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with the single parameter 'route_id' documented as 'The ID of the route to retrieve'. The description adds no additional meaning beyond this, such as format examples or constraints, so it meets the baseline score when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('route') with specificity ('detailed information about a specific route'), making the purpose evident. However, it does not explicitly differentiate from sibling tools like 'list_routes' or 'get_plan', which would require more nuance to achieve a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, such as 'list_routes' for multiple routes or other 'get_' tools for different resources. It lacks context on prerequisites, exclusions, or comparative use cases, leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_workoutB

Get detailed information about a specific workout

ParametersJSON Schema
NameRequiredDescriptionDefault
workout_idYesThe ID of the workout to retrieve

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It states it 'gets' information, implying a read-only operation, but doesn't disclose behavioral traits like error handling (e.g., if workout_id is invalid), authentication needs, rate limits, or what 'detailed information' includes (e.g., fields, format). For a tool with no annotations, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly. Every part of the sentence contributes to understanding the tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (single parameter, no output schema, no annotations), the description is minimally complete but lacks depth. It covers the basic purpose but doesn't address usage guidelines, behavioral details, or output information. For a simple read tool, it's adequate but leaves clear gaps that could hinder effective agent use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'workout_id' documented in the schema as 'The ID of the workout to retrieve'. The description adds no additional meaning beyond this, such as ID format or examples. With high schema coverage, the baseline is 3, as the schema adequately handles parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('detailed information about a specific workout'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'list_workouts' or 'get_plan', which would require mentioning it retrieves a single workout by ID versus listing multiple workouts or getting other entity types.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid workout_id), contrast with 'list_workouts' for multiple workouts, or specify contexts like after listing workouts to get details. The description is standalone without usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_plansC

List plans from Wahoo Cloud API

ParametersJSON Schema
NameRequiredDescriptionDefault
external_idNoFilter plans by external ID

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavior. It only says 'List plans', implying a read operation, but omits details like permissions, side effects, or return format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely brief (7 words), which is efficient but lacks necessary detail. It is not overly verbose, but the conciseness comes at the cost of completeness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and only one optional parameter, the description fails to explain what the list returns (e.g., array of plan objects), pagination, or filtering behavior. It is incomplete for practical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has one parameter with a description, achieving 100% coverage. The tool description adds no extra meaning beyond what the schema provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states 'List plans from Wahoo Cloud API', clearly indicating the action (list) and resource (plans). It's distinct from sibling 'get_plan' which implies a single plan retrieval, but it doesn't explicitly differentiate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidelines are provided. The description does not specify when to use this tool versus alternatives like get_plan or other list tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_power_zonesB

List power zones from Wahoo Cloud API

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must disclose behavioral traits. It only states it lists power zones, with no info on authentication needs, pagination, rate limits, or data freshness.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words. For a tool with no parameters, it is appropriately concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and sibling tools, the description should clarify how list differs from get or other operations. It fails to provide enough context for correct invocation without prior knowledge.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so the description is the sole source of meaning. It adds value by naming the resource, but lacks details on what constitutes a power zone or the output structure.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists power zones from the Wahoo Cloud API. It uses a specific verb and resource, but does not differentiate from sibling tools like get_power_zone.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, such as get_power_zone for a single zone. No pre-conditions or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_routesC

List routes from Wahoo Cloud API

ParametersJSON Schema
NameRequiredDescriptionDefault
external_idNoFilter routes by external ID

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It fails to disclose important behaviors such as authentication requirements, pagination, or read-only nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single concise sentence with no unnecessary words. However, it could be more informative without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (list with one optional filter), the description is adequate but lacks return value information and behavioral context, which would be important given no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and includes a parameter description. The tool description adds no new meaning beyond the schema, so baseline score is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description states 'List routes' with source, clearly identifying the resource and action. It distinguishes from sibling tools like list_workouts by referencing a different resource type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. With siblings present, it would be beneficial to recommend this over list_workouts for routes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_workoutsC

List workouts from Wahoo Cloud API

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoPage number (default: 1)
per_pageNoNumber of items per page (default: 30)
start_dateNoFilter workouts created after this date (ISO 8601 format)
end_dateNoFilter workouts created before this date (ISO 8601 format)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only states 'List workouts' and does not mention pagination, filtering behavior, authentication, or any side effects. The schema parameter descriptions are not repeated in the tool description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no wasted words, but it is slightly under-specified. It earns its place but could be longer with benefit.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description should explain what the response contains, how pagination works, and filtering date format. It lacks these details, making it incomplete for an agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description does not add extra meaning beyond the schema; it does not explain date format or pagination behavior in prose.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'List' and resource 'workouts', distinguishing it from sibling tools like create_workout and list_plans, though it does not explicitly differentiate from other list tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, no context about prerequisites or when not to use it. With siblings like list_plans, list_routes, users need more direction.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 9 tool updatesv0.1.0
    • First observedcreate_plan
    • First observedget_plan
    • First observedget_power_zone
    • First observedget_route
    • First observedget_workout
    • First observedlist_plans
    • First observedlist_power_zones
    • First observedlist_routes
    • First observedlist_workouts
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.3/5.0

Scored across 9 tools

Disambiguation5/5

Every tool has a clearly distinct purpose targeting specific resources (plans, power zones, routes, workouts) with clear action verbs (create, get, list). There is no ambiguity or overlap between tools, as each tool name precisely indicates what resource it operates on and what action it performs.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case throughout. The naming convention is perfectly predictable: create_plan, get_plan, list_plans, get_power_zone, list_power_zones, etc. There are no deviations or mixed styles.

Tool Count5/5

With 9 tools, this server is well-scoped for managing Wahoo fitness resources. Each tool earns its place by covering distinct operations (create, get, list) across four resource types (plans, power zones, routes, workouts), providing a balanced and focused toolset.

Completeness3/5

The server covers get and list operations comprehensively for all four resource types, plus create for plans. However, there are notable gaps: no update or delete operations for any resource, and create is missing for power zones, routes, and workouts. This limits full lifecycle management.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • whoop-mcp

    AshwanthramKL
    A
    license
    Not graded
    quality
    D
    maintenance
    A local MCP server providing read-only access to WHOOP fitness data via direct OAuth, with a local SQLite cache for offline queries.
    51 PyPI
    MIT

  • Wahoo MCP Server

    ClemensHar
    A
    license
    B
    quality
    C
    maintenance
    A Model Context Protocol (MCP) server for interacting with the Wahoo Cloud API, focusing on reading workout information.
    10
    GPL 3.0