garmin-mcp

A Model Context Protocol (MCP) server that provides AI assistants like Claude with access to your Garmin Connect health and fitness data.

Overview

This MCP server enables Claude Desktop (and other MCP-compatible clients) to query your Garmin data on demand, including:

• Daily Health Metrics: Sleep Score, Training Readiness, Body Battery, HRV, Resting Heart Rate, Stress
• Activity Data: Workouts, runs, walks, cycling sessions with duration, distance, heart rate, and calories
• Sleep Analysis: Detailed sleep stages, timing, and score breakdowns
• Trend Analysis: Query metrics across date ranges for pattern recognition

No scheduled jobs, no CSV files, no stale data. Just live access to your Garmin Connect data when you need it.

Features

• On-Demand Data Access: Query your Garmin data in real-time during conversations
• Date Range Queries: Retrieve metrics across multiple days for trend analysis (up to 30 days)
• Secure Authentication: Uses Garmin's OAuth flow with persistent token storage
• Comprehensive Metrics: Access the same data you see in Garmin Connect
• Zero Maintenance: Tokens persist for ~1 year; no cron jobs or scheduled tasks

Prerequisites

• Python 3.10 - 3.13 (3.14 is not yet supported by dependencies)
• A Garmin Connect account with a compatible Garmin device syncing data
• Claude Desktop (or another MCP-compatible client)

Installation

1. Clone the Repository

cd ~/Dev
git clone https://github.com/shawnduggan/garmin-mcp.git
cd garmin-mcp

2. Create Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

Configuration

There are two ways to provide your Garmin credentials: environment file (recommended for initial setup) or Claude Desktop config (recommended for ongoing use).

Option A: Environment File (Recommended for Setup)

1. Create your environment file:

   cp .env.example .env

1. Edit .env with your Garmin Connect credentials:

   # Garmin Connect Credentials
   [email protected]
   GARMIN_PASSWORD=your_garmin_password

1. Run initial authentication:

   python -m garmin_mcp.auth

If successful, you'll see:

   Authenticating as [email protected]...
   ✓ Authentication successful!
   ✓ Session saved to /Users/shawn/Dev/garmin-mcp/.garth
   ✓ Tokens are valid for approximately one year.
   ✓ Verification: Today's step count = 4521

1. Security Note: After successful authentication, you can delete the .env file. The session tokens in .garth/ are sufficient for ongoing use.

Option B: Claude Desktop Config with Credentials

If you prefer to keep credentials in the Claude Desktop config (they're passed as environment variables to the MCP server):

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/shawn/Dev/garmin-mcp/venv/bin/python",
      "args": ["-m", "garmin_mcp.server"],
      "cwd": "/Users/shawn/Dev/garmin-mcp",
      "env": {
        "GARMIN_EMAIL": "[email protected]",
        "GARMIN_PASSWORD": "your_garmin_password"
      }
    }
  }
}

Claude Desktop Setup

Add the garmin-mcp server to your Claude Desktop configuration:

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

#### Minimal Configuration (After Token Auth)

If you've already authenticated and have tokens saved in .garth/:

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/shawn/Dev/garmin-mcp/venv/bin/python",
      "args": ["-m", "garmin_mcp.server"],
      "cwd": "/Users/shawn/Dev/garmin-mcp"
    }
  }
}

#### Full Configuration (With Credentials)

If you want credentials available for re-authentication:

{
  "mcpServers": {
    "garmin": {
      "command": "/Users/shawn/Dev/garmin-mcp/venv/bin/python",
      "args": ["-m", "garmin_mcp.server"],
      "cwd": "/Users/shawn/Dev/garmin-mcp",
      "env": {
        "GARMIN_EMAIL": "[email protected]",
        "GARMIN_PASSWORD": "your_garmin_password"
      }
    }
  }
}

#### Adding to Existing Configuration

If you already have other MCP servers configured, add garmin to your existing mcpServers object:

{
  "mcpServers": {
    "some-other-server": {
      "...": "..."
    },
    "garmin": {
      "command": "/Users/shawn/Dev/garmin-mcp/venv/bin/python",
      "args": ["-m", "garmin_mcp.server"],
      "cwd": "/Users/shawn/Dev/garmin-mcp"
    }
  }
}

Restart Claude Desktop

After saving your configuration, fully quit and restart Claude Desktop for the MCP server to become available.

Available Tools

get_daily_summary

Retrieve comprehensive health metrics for a specific date.

Parameters:

Returns:

{
  "date": "2026-01-03",
  "sleep_score": 73,
  "training_readiness": 58,
  "body_battery_high": 85,
  "body_battery_low": 23,
  "hrv_status": "BALANCED",
  "hrv_value": 24,
  "resting_heart_rate": 52,
  "avg_stress": 28,
  "steps": 8432
}

Metric semantics:

• Missing or unusable metrics remain null; the adapter does not estimate values.
• training_readiness prefers a matching-calendarDate, primary-tracker

AFTER_WAKEUP_RESET record. If several morning records exist, the newest usable timestamp wins. A morning record without a timestamp is still eligible; a supplied but malformed timestamp is rejected. Without a morning record, the newest timestamped record for that date is used, not relabeled as morning. Numeric scores must be between 0 and 100 (including zero).

• When a readiness record is selected, three additional fields identify it:

training_readiness_context and training_readiness_timestamp contain the original values (or null if absent); training_readiness_selection is primary_tracker_morning, latest, or legacy. Legacy single dictionaries are accepted with a valid score and either no calendar date or the requested date. These provenance fields are omitted when no record is selected.

• body_battery_high / body_battery_low are extrema of observed samples,

not guaranteed full-day extrema. Only matching-date daily records with unambiguous timestamp/level descriptor indices and valid numeric samples are used. Levels from 0 through 100 are valid; malformed samples are skipped. No samples means both fields are null. The daily record's date defines the day; sample timestamps are not converted into the server's local timezone.

• resting_heart_rate is a positive finite numeric scalar from the requested

day's allMetrics.metricsMap.WELLNESS_RESTING_HEART_RATE records. When that endpoint is absent, malformed, or fails, the adapter uses a valid restingHeartRate from the user summary (rejecting an explicitly different calendar date). Steps, stress, sleep and HRV retain their existing fields.

get_summary_range

Retrieve health metrics for a date range, useful for trend analysis.

Parameters:

Limits: Maximum 30-day range per request.

Returns:

{
  "start_date": "2025-12-28",
  "end_date": "2026-01-03",
  "days": 7,
  "summaries": [
    {"date": "2025-12-28", "sleep_score": 80, "...": "..."},
    {"date": "2025-12-29", "sleep_score": 64, "...": "..."}
  ]
}

get_activities

Retrieve fitness activities (runs, walks, cycling, strength training, etc.) for a specific date.

Parameters:

Returns:

{
  "date": "2026-01-02",
  "count": 1,
  "activities": [
    {
      "name": "Indoor Walking",
      "type": "walking",
      "start_time": "2026-01-02T11:30:00",
      "duration_minutes": 32.5,
      "distance_km": 2.8,
      "calories": 185,
      "avg_hr": 118,
      "max_hr": 135,
      "training_effect_aerobic": 2.3,
      "training_effect_anaerobic": 0.1
    }
  ]
}

get_sleep_details

Retrieve detailed sleep data including stages, timing, and score breakdown.

Parameters:

Returns:

{
  "date": "2026-01-03",
  "sleep_start": "23:15",
  "sleep_end": "06:42",
  "total_sleep_minutes": 387,
  "deep_sleep_minutes": 62,
  "light_sleep_minutes": 198,
  "rem_sleep_minutes": 89,
  "awake_minutes": 38,
  "sleep_scores": {
    "overall": {"value": 73},
    "quality": {"value": 68},
    "recovery": {"value": 71},
    "duration": {"value": 82}
  }
}

Usage Examples

Once configured, you can ask Claude things like:

Daily Check-ins:

• "What were my Garmin stats yesterday?"
• "How did I sleep last night?"
• "What's my Training Readiness today?"

Trend Analysis:

• "Show me my sleep and HRV trends for the past week"
• "Compare my recovery metrics from last week to this week"
• "What's my average resting heart rate been this month?"

Activity Review:

• "What activities did I log on Tuesday?"
• "Pull my workout data for the past 7 days"
• "How many steps have I averaged this week?"

Health Correlations:

• "On days when my sleep score was below 60, what was my stress level?"
• "Show me my Body Battery patterns for December"

Troubleshooting

Authentication Errors

If you see authentication failures:

1. Delete existing tokens:

   rm -rf /Users/shawn/Dev/garmin-mcp/.garth

1. Wait 15 minutes (Garmin rate limits failed attempts)

1. Verify credentials by logging into connect.garmin.com in a browser

1. Re-authenticate:

   cd /Users/shawn/Dev/garmin-mcp
   source venv/bin/activate
   python -m garmin_mcp.auth

Two-Factor Authentication (2FA)

If you have 2FA enabled on your Garmin account:

• You may need to create an app-specific password
• Or temporarily disable 2FA during initial authentication
• Once tokens are saved, 2FA won't affect subsequent use

Token Expiration

Tokens are valid for approximately one year. If requests start failing after extended use:

1. Delete the .garth directory
2. Re-run authentication
3. Restart Claude Desktop

Rate Limiting

Garmin may temporarily block requests if you query too frequently. The server includes automatic retry logic, but if you encounter persistent failures:

• Wait 15-30 minutes before trying again
• Avoid making many rapid requests in succession

MCP Server Not Appearing in Claude

1. Verify your claude_desktop_config.json syntax is valid JSON
2. Check the path to your Python virtual environment is correct
3. Ensure you've fully quit and restarted Claude Desktop
4. Check Claude Desktop's logs for MCP connection errors

"No data available" Responses

• Ensure your Garmin device has synced recently
• Some metrics (like Training Readiness) require specific Garmin devices
• Check that data exists for the requested date in the Garmin Connect app

Project Structure

garmin-mcp/
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
└── src/
    └── garmin_mcp/
        ├── __init__.py
        ├── server.py      # MCP server implementation
        └── auth.py        # Authentication module

How It Works

1. Authentication: On first run, the server authenticates with Garmin Connect using your credentials and stores OAuth tokens in the .garth directory.

1. Token Persistence: Subsequent requests use the stored tokens, so your credentials aren't needed after initial setup.

1. MCP Protocol: Claude Desktop launches the server as a subprocess and communicates via the Model Context Protocol over stdin/stdout.

1. On-Demand Queries: When you ask Claude about your Garmin data, it calls the appropriate tool, which fetches live data from the Garmin Connect API.

Acknowledgments

This project was inspired by AI_Fitness by johnson4601, which demonstrated the approach for extracting Garmin data using the garminconnect library.

The Garmin Connect API access is powered by the garminconnect Python library and garth for OAuth token management.

License

MIT License - see LICENSE for details.

Tests

Run the adapter regression suite with the existing environment:

venv/bin/python -W error -m unittest discover -s tests -v

Tests use synthetic response shapes, fake authentication/session operations, and blocked outbound socket connections. They do not read saved tokens, log in to Garmin, or make network requests. No additional test dependency is required.

Contributing

Contributions are welcome! Please:

1. Open an issue to discuss proposed changes before submitting a PR
2. Follow existing code style
3. Add tests for new functionality
4. Update documentation as needed

Disclaimer

This project is not affiliated with or endorsed by Garmin. It accesses the unofficial Garmin Connect API, which may change without notice. Use responsibly and in accordance with Garmin's terms of service.

Support

If you encounter issues:

1. Check the Troubleshooting section
2. Search existing GitHub Issues
3. Open a new issue with:

• Your Python version
• Your operating system
• The full error message
• Steps to reproduce