Skip to main content

MCP Tools

The @wellpipe/garmin package includes 32 MCP (Model Context Protocol) tools that enable AI assistants to query Garmin Connect data.

Tool Categories​

CategoryToolsDescription
Sleep3Sleep sessions, stages, quality
Health9HRV, stress, body battery, heart rate, steps, weight, hydration
Activities10Activities, workouts, training status
Training10VO2 max, race predictions, fitness age, goals, records

Using Tools​

In MCP Server​

import { createMcpServer } from '@wellpipe/garmin';

const server = createMcpServer(tokenProvider);

// The server exposes all tools via MCP protocol
server.listen();

Tool Definitions​

Each tool is defined with:

interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: z.ZodSchema;
  handler: (input: unknown, apis: GarminApis) => Promise<ToolResult>;
}

Sleep Tools​

garmin-get-sleep​

Get sleep data for a specific date.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Sleep session with stages, duration, SpO2, respiration, and quality scores.

garmin-get-sleep-range​

Get sleep data for a date range.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Array of sleep sessions for the range.

garmin-get-recent-sleep​

Get recent sleep data.

Input:

{
  days?: number;  // Number of days (default: 7)
}

Output: Array of recent sleep sessions.

Health Tools​

garmin-get-hrv​

Get HRV (heart rate variability) data.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: HRV value, status, baseline comparison.

garmin-get-stress​

Get stress levels for a date.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Stress values throughout the day with averages.

garmin-get-body-battery​

Get Body Battery energy data.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Body Battery values, charged/drained amounts.

garmin-get-heart-rate​

Get all-day heart rate data.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Heart rate values, resting HR, max HR, zones.

garmin-get-steps​

Get step count for today.

Input: None

Output: Current steps, goal, distance, calories.

garmin-get-steps-range​

Get step counts for a date range.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Daily step counts for the range.

garmin-get-weight​

Get recent weight measurements.

Input:

{
  days?: number;  // Number of days (default: 30)
}

Output: Weight measurements with body composition (if available).

garmin-get-weight-by-date​

Get weight for a specific date.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Weight measurement for that date.

garmin-get-hydration​

Get hydration data.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Water intake, goal, sweat loss.

Activity Tools​

garmin-get-activities​

Get a list of recent activities.

Input:

{
  limit?: number;  // Number of activities (default: 20)
  start?: number;  // Pagination offset (default: 0)
}

Output: Array of activities with summary info.

garmin-get-activities-by-date​

Get activities for a specific date.

Input:

{
  date: string;  // YYYY-MM-DD (required)
}

Output: Activities that occurred on that date.

garmin-get-activity-by-id​

Get an activity by its ID.

Input:

{
  activityId: string;  // Activity ID (required)
}

Output: Full activity details.

garmin-get-activity-details​

Get detailed metrics for an activity.

Input:

{
  activityId: string;  // Activity ID (required)
}

Output: Detailed metrics including polyline, HR zones, laps.

garmin-get-activity-splits​

Get split data for an activity.

Input:

{
  activityId: string;  // Activity ID (required)
}

Output: Mile/km splits with pace and heart rate.

garmin-get-activity-weather​

Get weather conditions during an activity.

Input:

{
  activityId: string;  // Activity ID (required)
}

Output: Temperature, humidity, wind conditions.

garmin-get-workouts​

Get scheduled workouts.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Scheduled workout plans.

garmin-get-workout-by-id​

Get a specific workout by ID.

Input:

{
  workoutId: string;  // Workout ID (required)
}

Output: Workout details and steps.

garmin-get-training-readiness​

Get training readiness score.

Input: None

Output: Training readiness with contributing factors.

garmin-get-training-status​

Get training status.

Input: None

Output: Training status (productive, maintaining, etc.).

Training Tools​

garmin-get-race-predictions​

Get race time predictions.

Input: None

Output: Predicted times for 5K, 10K, half marathon, marathon.

garmin-get-vo2-max​

Get VO2 Max estimate.

Input: None

Output: VO2 Max value with fitness category.

garmin-get-hill-score​

Get hill score data.

Input: None

Output: Uphill/downhill endurance scores.

garmin-get-endurance-score​

Get endurance score.

Input: None

Output: Overall endurance rating.

garmin-get-lactate-threshold​

Get lactate threshold data.

Input: None

Output: Lactate threshold heart rate and pace.

garmin-get-intensity-minutes​

Get intensity minutes data.

Input:

{
  startDate: string;  // YYYY-MM-DD (required)
  endDate: string;    // YYYY-MM-DD (required)
}

Output: Moderate and vigorous intensity minutes.

garmin-get-fitness-age​

Get fitness age estimate.

Input: None

Output: Fitness age based on VO2 Max.

garmin-get-body-battery-report​

Get Body Battery report/trends.

Input:

{
  days?: number;  // Number of days (default: 7)
}

Output: Body Battery trends and patterns.

garmin-get-active-goals​

Get active goals.

Input: None

Output: Current fitness goals and progress.

garmin-get-personal-records​

Get personal records.

Input: None

Output: PRs for running, cycling, swimming, etc.

Tool Registration​

Tools are automatically registered when creating an MCP server:

import { allTools } from '@wellpipe/garmin';

// Get all tool definitions
console.log(`Registered ${allTools.length} tools`);

// Tools are grouped by category
import { sleepTools, healthTools, activityTools, trainingTools } from '@wellpipe/garmin';

Creating Custom Tools​

You can create additional tools using the existing APIs:

import { defineTool } from '@wellpipe/garmin';
import { z } from 'zod';

const customTool = defineTool({
  name: 'garmin-weekly-summary',
  description: 'Get a summary of health data for the past week',
  inputSchema: z.object({}),
  handler: async (input, apis) => {
    const endDate = new Date().toISOString().split('T')[0];
    const startDate = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000)
      .toISOString()
      .split('T')[0];

    const [sleep, hrv, stress] = await Promise.all([
      apis.sleep.getSleepRange(startDate, endDate),
      apis.hrv.getHRVByDate(endDate),
      apis.stress.getStressByDate(endDate),
    ]);

    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            period: { start: startDate, end: endDate },
            sleepDays: sleep.length,
            currentHRV: hrv?.hrvValue,
            currentStress: stress?.averageStressLevel,
          }),
        },
      ],
    };
  },
});

Tool Result Format​

All tools return results in MCP format:

interface ToolResult {
  content: Array<{
    type: 'text';
    text: string;  // JSON-stringified data
  }>;
  isError?: boolean;
}

Example:

{
  content: [
    {
      type: 'text',
      text: '{"sleepTimeSeconds": 28800, "deepSleepSeconds": 7200, ...}'
    }
  ]
}