Garmin MCP Server

A Model Context Protocol (MCP) server that connects Claude Desktop to your real Garmin Connect running data stored in a local SQLite database.

Setup for Claude Desktop

1. Install Dependencies

npm install

2. Configure Garmin Credentials

Create a .env file in the project root:

cp .env.example .env

Edit .env and add your Garmin Connect credentials:

GARMIN_USERNAME=your-email@example.com
GARMIN_PASSWORD=your-password

3. Download Your Garmin Data

npm run download

This downloads all your activities from Garmin Connect to a local SQLite database at data/garmin-data.db.

4. Configure Claude Desktop

First, get the absolute path to this project:

pwd

This will output something like /Users/yourusername/Code/garmin-mcp-server.

macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: Edit ~/.config/Claude/claude_desktop_config.json

Windows: Run cd to get the path, then edit %APPDATA%\Claude\claude_desktop_config.json

Add this configuration (replace the path with your actual project path):

{
  "mcpServers": {
    "garmin-mcp-server": {
      "command": "npx",
      "args": ["-y", "tsx", "/Users/yourusername/Code/garmin-mcp-server/src/index.ts"],
      "cwd": "/Users/yourusername/Code/garmin-mcp-server"
    }
  }
}

Replace /Users/yourusername/Code/garmin-mcp-server with your actual path from the pwd command.

5. Restart Claude Desktop

After restarting, you can ask Claude:

• "Sync my latest Garmin activities"
• "Show me my 5 most recent runs"
• "What's my average pace this month?"
• "Analyze my running performance trends"
• "How many kilometers did I run this year?"

Features

• Local SQLite Database - Your data stored locally for fast access
• Auto-Sync - Update your data from Garmin Connect directly through Claude
• SQL Queries - Run custom queries to analyze your training data
• Comprehensive Metrics - Heart rate, pace, cadence, power, VO2 max, and more
• AI Analysis - Let Claude analyze your running trends and performance
• Privacy-First - All data stays on your machine

Self-Hosting with Docker

Deploy your own instance using Docker for use with Claude, ChatGPT, or any MCP-compatible client.

Quick Start with Docker Compose

1. Create a directory and download the compose file:

mkdir garmin-mcp && cd garmin-mcp
curl -O https://raw.githubusercontent.com/vnglst/garmin-mcp-server/main/docker-compose.yml

2. Create a .env file:

GARMIN_USERNAME=your-email@example.com
GARMIN_PASSWORD=your-password
API_KEY=your-secret-api-key

3. Start the server:

docker compose up -d

The server runs at http://localhost:3000 with:

• MCP endpoint: POST /mcp
• Health check: GET /health

Coolify Deployment

1. Create a new service from Git repository
2. Set the following environment variables:
   • GARMIN_USERNAME: Your Garmin Connect email
   • GARMIN_PASSWORD: Your Garmin Connect password
   • API_KEY: Secret key for authentication
   • PORT: 3000 (default)
3. Configure health check path: /health
4. Deploy

Using the Pre-built Image

docker run -d \
  --name garmin-mcp-server \
  -p 3000:3000 \
  -e GARMIN_USERNAME=your-email@example.com \
  -e GARMIN_PASSWORD=your-password \
  -e API_KEY=your-secret-key \
  -v garmin-data:/app/data \
  ghcr.io/vnglst/garmin-mcp-server:latest

MCP Client Configuration

Configure your MCP client to connect to the HTTP endpoint:

{
  "mcpServers": {
    "garmin": {
      "url": "https://your-server.example.com/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}

Environment Variables

Variable	Required	Description
GARMIN_USERNAME	Yes	Garmin Connect email
GARMIN_PASSWORD	Yes	Garmin Connect password
API_KEY	No	API key for authentication (recommended)
PORT	No	Server port (default: 3000)

Available MCP Tools

The server exposes three tools that Claude can use:

1. get-schema

Get the database schema to understand available data fields.

Example usage in Claude:

• "What data fields are available in my running database?"
• "Show me the database schema"

2. run-query

Execute SELECT queries against your activities database.

Example usage in Claude:

• "Show me my 10 most recent runs"
• "What's my average heart rate this month?"
• "Find all runs longer than 10km"
• "Calculate my total distance this year"

Security: Only SELECT queries are allowed - no data modification.

3. sync-activities

Download and sync new activities from Garmin Connect to the local database.

Example usage in Claude:

• "Sync my latest Garmin activities"
• "Update my running data"
• "Check for new workouts"

Returns a summary showing:

• Number of new activities downloaded
• Total activities in the database
• Date of your latest activity

What Data You Get

All data from your Garmin device stored in a SQLite database (58+ fields):

Basic Metrics:

• Activity ID, name, description, timestamps (local & GMT)
• Activity type, location name
• Distance, duration, elapsed duration, moving duration
• Calories, steps, lap count

Heart Rate Data:

• Average/max heart rate
• Lactate threshold BPM
• Time in each HR zone (1-5)
• VO2 Max value

Speed & Pace:

• Average/max speed
• Fastest splits (1K, 5K, 10K, mile)

Running Dynamics:

• Average/max stride length
• Average/max cadence (including double cadence)
• Average vertical oscillation
• Average ground contact time
• Vertical ratio, vertical speed

Training Load & Intensity:

• Activity training load
• Training effect (aerobic/anaerobic)
• Vigorous/moderate intensity minutes

Elevation:

• Elevation gain/loss
• Min/max elevation

Power Metrics:

• Average/max power
• Grit and Flow scores

How It Works

1. Initial Setup: Run npm run download to download all your activities from Garmin Connect into a local SQLite database
2. Claude Integration: The MCP server exposes tools that Claude can use to query your data
3. Stay Updated: Use the sync-activities tool in Claude to download new activities anytime
4. Flexible Queries: Claude can run SQL queries to analyze your data in any way you want

Development

# Download/update activities from Garmin
npm run download

# Build TypeScript to JavaScript
npm run build

# Test MCP server manually
npm run test:mcp

# Run server directly (for testing)
npm start

Note: When using with Claude Desktop via the tsx configuration, you don't need to build - changes to TypeScript files are automatically picked up.

Troubleshooting

Authentication Issues

• Verify credentials in .env file (GARMIN_USERNAME and GARMIN_PASSWORD)
• Ensure you can log into connect.garmin.com manually
• Try logging in via web browser first
• Check that your password doesn't contain special characters that need escaping

Database Not Found

• Run npm run download first to create the database
• Check that data/garmin-data.db exists in your project directory
• Verify the database file isn't corrupted (try deleting and re-downloading)

Sync Not Working in Claude

• Restart Claude Desktop after configuration changes
• Check Claude Desktop logs for error messages
• Verify the paths in claude_desktop_config.json are absolute, not relative
• Ensure .env file exists in the project root directory

Query Errors

• Only SELECT queries are allowed (INSERT, UPDATE, DELETE are blocked)
• Use the get-schema tool to see available table columns
• Check SQL syntax is correct

Security & Privacy

Your data stays completely private:

• Credentials stored locally in .env file only
• Direct connection to Garmin Connect (no intermediary servers)
• All data stored in local SQLite database on your machine
• No third-party data sharing or cloud uploads
• Database queries run locally
• Only SELECT queries allowed (read-only access for Claude)

Technical Details

Architecture:

• TypeScript-based MCP server
• SQLite database for local storage
• Direct integration with Garmin Connect API (via garmin-connect library)
• Runs via tsx for development (no build step needed with Claude Desktop)
• MCP SDK for Claude Desktop integration

Database:

• Location: data/garmin-data.db
• Format: SQLite 3
• Updates: Incremental (only new activities downloaded)
• Contains: All activity data from Garmin Connect

Requirements

• Node.js 18+
• npm (comes with Node.js)
• Garmin Connect account with running/fitness activities
• Claude Desktop for MCP integration
• Garmin device that syncs to Garmin Connect (watch, bike computer, etc.)

Contributing

Feel free to open issues or submit pull requests for:

• Bug fixes
• New data fields to track
• Additional MCP tools
• Documentation improvements

License

MIT

---

Note: This project is not affiliated with, endorsed by, or sponsored by Garmin Ltd. or Garmin International, Inc.