# 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:
   ```bash
   cd garmin-mcp
   npm install
   ```

3. Build the TypeScript code:
   ```bash
   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:**
   ```bash
   touch .env
   ```

2. **Add your credentials to the .env file:**
   ```bash
   # .env
   GARMIN_USERNAME=your.email@example.com
   GARMIN_PASSWORD=your_secure_password
   GARMIN_AUTO_AUTH=true
   ```

3. **Secure the file:**
   ```bash
   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`

```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`](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:
```bash
npm run dev
```

To build:
```bash
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