Garmin MCP Server

A Model Context Protocol (MCP) server that integrates with Garmin Connect to provide activity insights and training suggestions for Claude Desktop.

Features

• Activity Tracking: Retrieve recent activities from Garmin Connect
• Activity Insights: Get detailed analysis of individual activities or activity patterns
• Training Suggestions: AI-powered recommendations based on your training data and health metrics
• Health Metrics: Access to comprehensive health data including heart rate, sleep, stress, and body battery
• Performance Analysis: Automated analysis of training load, recovery, and performance trends

Installation

1. Clone or download this repository

2. Install dependencies:

   cd garmin-mcp
   npm install
   

3. Build the TypeScript code:

   npm run build
   

Configuration

Environment Variables Setup (Recommended)

For security and convenience, you can store your Garmin Connect credentials in environment variables:

1. Create a .env file:

   touch .env
   

2. Add your credentials to the .env file:

   # .env
   GARMIN_USERNAME=your.email@example.com
   GARMIN_PASSWORD=your_secure_password
   GARMIN_AUTO_AUTH=true
   

3. Secure the file:

   chmod 600 .env
   

With environment variables configured, the MCP server will:

• Automatically authenticate on startup (if GARMIN_AUTO_AUTH=true)
• Use your stored credentials as fallback for authentication commands
• Keep your credentials secure and out of version control

Claude Desktop Setup

Add the MCP server to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "garmin": {
      "command": "node",
      "args": ["path/to/garmin-mcp/dist/index.js"]
    }
  }
}

Triathlon Expert Mode (Recommended)

For the best coaching experience, add the triathlon expert prompt to your Claude project:

1. Create or open your project in Claude Desktop
2. Add the expert prompt by copying the contents of TRIATHLON_EXPERT_PROMPT.md to your project's context
3. Enable code execution in your project settings for accurate calculations

This prompt transforms Claude into a world-class triathlon coach that:

• Uses code for all calculations to prevent estimation errors
• Provides data-driven training insights
• Offers personalized coaching based on your Garmin data
• Analyzes performance trends with scientific accuracy

Garmin Connect Authentication

The MCP server supports multiple authentication methods:

Option 1: Environment Variables (Recommended)

Set up your .env file as described above. The server will automatically authenticate on startup.

Option 2: Manual Authentication

Use the authenticate_garmin tool within Claude Desktop. If you have environment variables set, you can simply call:

• "Please authenticate with Garmin Connect" (uses env vars)
• Or provide credentials manually: "Authenticate with username X and password Y"

Important: Credentials are only stored in memory during the session and are not persisted to disk.

Available Tools

1. authenticate_garmin

Authenticate with Garmin Connect using your username and password.

Parameters:

• username: Your Garmin Connect username
• password: Your Garmin Connect password

2. get_activities

Retrieve recent activities from Garmin Connect.

Parameters:

• days (optional): Number of days to look back (default: 30)
• limit (optional): Maximum number of activities to return (default: 50)

3. get_activity_insights

Get detailed insights for a specific activity or recent activities.

Parameters:

• activityId (optional): Specific activity ID to analyze
• days (optional): Number of days to analyze if no activity ID specified (default: 7)

4. get_training_suggestions

Get AI-powered training suggestions based on recent activities and performance.

Parameters:

• activityType (optional): Type of activity to focus on ('running', 'cycling', 'swimming', 'strength', 'all')
• days (optional): Number of days of history to consider (default: 14)

5. get_health_metrics

Get health and wellness metrics from Garmin Connect.

Parameters:

• startDate (optional): Start date in YYYY-MM-DD format
• endDate (optional): End date in YYYY-MM-DD format
• metrics (optional): Specific metrics to retrieve (['heartRate', 'stress', 'sleep', 'bodyBattery', 'vo2Max'])

Usage Examples

Getting Started

1. Authenticate: "Please authenticate with my Garmin Connect account"
2. View Recent Activities: "Show me my recent activities"
3. Get Insights: "Analyze my running performance from the last week"
4. Training Advice: "Give me training suggestions based on my recent workouts"

Detailed Analysis

• "What are my sleep patterns and how do they affect my recovery?"
• "Analyze my heart rate trends during cycling activities"
• "Give me specific recommendations for improving my running pace"
• "How is my training load compared to my recovery metrics?"

Data Privacy

• This MCP server accesses your Garmin Connect data only during active sessions
• No data is stored permanently on your device
• Authentication credentials are not persisted between sessions
• All data processing happens locally on your machine

Dependencies

• @modelcontextprotocol/sdk: MCP SDK for TypeScript
• garmin-connect: Unofficial Garmin Connect API client
• zod: Schema validation

Development

To run in development mode:

npm run dev

To build:

npm run build

Limitations

• Requires valid Garmin Connect credentials
• Depends on the unofficial Garmin Connect API (may break with Garmin updates)
• Some advanced metrics may not be available depending on your Garmin device
• Rate limiting by Garmin Connect may apply

Troubleshooting

Authentication Issues

• Ensure your Garmin Connect credentials are correct
• Check if your account requires two-factor authentication (not currently supported)
• Verify your account is not locked or suspended

Missing Data

• Some metrics require specific Garmin devices
• Ensure your device is synced with Garmin Connect
• Check that the requested date range contains activities

Connection Issues

• Verify your internet connection
• Check if Garmin Connect services are operational
• Try authenticating again if the session has expired

License

MIT License - see LICENSE file for details