Skip to content
BranchesTags

Repository files navigation

Garmin MCP Server

A Model Context Protocol (MCP) server that gives compatible AI clients access to Garmin Connect activity and health data stored in SQLite, plus tools for managing Garmin workouts.

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

Create the local data directory and download your activities:

mkdir -p data
npm run download

This downloads your activities and lap data 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"
  • "Sync my daily resting heart rate"
  • "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 - Activity, lap, and daily heart-rate data for fast access
  • Incremental sync - Update Garmin data through an MCP client or the command line
  • Read-only SQL tools - Analyze training data with custom SELECT queries
  • Workout management - Create, rename, schedule, unschedule, and delete Garmin workouts
  • Two transports - Local stdio and self-hosted Streamable HTTP
  • Optional HTTP authentication - Protect remote access with a bearer token

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. Clone this repository:
git clone https://github.com/vnglst/garmin-mcp-server.git
cd garmin-mcp-server
  1. Create a .env file and replace the example values:
cat > .env <<'EOF'
GARMIN_USERNAME=your-email@example.com
GARMIN_PASSWORD=your-password
API_KEY=your-secret-api-key
EOF
  1. Create the initial database on the host. The production image does not include the download CLI, so the database must exist before the container starts:
npm ci
mkdir -p data
npm run download
  1. Create the container, copy the database into its persistent volume, and start it:
docker compose create
docker compose cp ./data/garmin-data.db garmin-mcp-server:/app/data/garmin-data.db
docker compose up -d

The Compose configuration builds the image from the checked-out source. 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. Mount persistent storage at /app/data and seed it with garmin-data.db
  5. Deploy

Using the Pre-built Image

Initialize a named volume from a database created with npm run download before starting the image:

docker volume create garmin-data
docker run --rm \
  -v "$PWD/data:/source:ro" \
  -v garmin-data:/target \
  alpine cp /source/garmin-data.db /target/garmin-data.db
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 For sync/workout tools Garmin Connect email
GARMIN_PASSWORD For sync/workout tools Garmin Connect password
API_KEY No Bearer token required by HTTP clients; strongly recommended outside an isolated local environment
PORT No Enables HTTP mode on this port; defaults to 3000 in Docker
HTTP_MODE No Set to true to enable HTTP mode without setting PORT
CORS_ORIGIN No Comma-separated allowed browser origins; CORS headers are omitted by default
MAX_SESSIONS No Maximum active HTTP MCP sessions (default: 100)
MAX_QUERY_CHARS No Maximum SQL query length (default: 50000)

Available MCP Tools

The server exposes activity-data tools and Garmin Connect workout-management tools.

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: One SELECT or WITH ... SELECT statement is allowed per call. Write statements and SQLite administrative statements are blocked.

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 activities"

Returns a summary showing:

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

4. sync-health

Incrementally sync daily heart-rate summaries from Garmin Connect. The first sync downloads the latest 30 days; later syncs refresh the newest stored day and add new days through today. Use startDate and endDate in YYYY-MM-DD format to backfill a specific range.

The daily_heart_rate table includes resting, minimum, maximum, and seven-day average resting heart rate. Metrics unavailable from a device are stored as NULL and can be queried with run-query.

Workout management

The following tools manage structured workouts in Garmin Connect:

Tool Description
list-workouts List saved workouts
get-workout Get a workout and all of its structured steps
create-workout Create a workout from a Garmin workout JSON object
rename-workout Rename a workout without changing its steps
delete-workout Permanently delete a saved workout
schedule-workout Add a workout to the Garmin calendar
list-scheduled-workouts List calendar entries for a month
get-scheduled-workout Get a calendar workout by schedule ID
unschedule-workout Remove a calendar entry without deleting the workout

Examples:

  • "Create a 5 x 3-minute running interval workout and schedule it tomorrow"
  • "Rename my VO2 max workout"
  • "Remove the duplicate scheduled workout but keep the saved workout"

Workout creation, renaming, scheduling, unscheduling, and deletion modify your Garmin Connect account. delete-workout removes the saved workout itself; unschedule-workout removes only one calendar entry.

What Data You Get

The SQLite database contains three tables as data is synced:

  • activities for activity summaries and performance metrics
  • activity_laps for per-lap pace, heart rate, cadence, running dynamics, elevation, and location metrics
  • daily_heart_rate for daily minimum, maximum, resting, and seven-day-average resting heart rate

Use the get-schema tool to inspect the exact current columns. Activity data includes:

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. MCP integration: The server exposes tools that compatible clients can use to query your data
  3. Stay updated: Use the sync-activities and sync-health tools to download new data anytime
  4. Flexible queries: The client can run read-only SQL queries to analyze your data

Development

# Download/update activities from Garmin
npm run download

# Build TypeScript to JavaScript
npm run build

# Run the unit test suite
npm test

# Run the stdio and HTTP smoke test (requires a build and local database)
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
  • If the database may be corrupted, back it up before recreating it with npm run download

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

For a local stdio installation:

  • Credentials are loaded from the local .env file and sent to Garmin Connect for authentication.
  • Synced data is stored in the local SQLite database.
  • Query access is read-only.

For a self-hosted HTTP installation, credentials and data reside on the host running the container, and MCP responses travel between that host and the configured client. Set a strong API_KEY, use HTTPS at the reverse proxy, restrict network access, and protect the persistent volume and .env file. Workout tools can modify the connected Garmin account; review destructive tool calls before approving them.

Technical Details

Architecture:

  • TypeScript-based MCP server
  • SQLite database for activity, lap, and health 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 with stdio and Streamable HTTP transports

Database:

  • Location: data/garmin-data.db
  • Format: SQLite 3
  • Updates: Incremental (only new activities downloaded)
  • Contains: activity summaries, activity laps, and synced daily heart-rate summaries from Garmin Connect

Requirements

  • Node.js 20 or 22 (the versions exercised in CI)
  • npm (comes with Node.js)
  • Garmin Connect account with running/fitness activities
  • An MCP-compatible client such as Claude Desktop, or an HTTP MCP client for self-hosting
  • 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.

About

MCP server providing Claude Desktop with access to Garmin Connect running data

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

3 forks
Report repository

Releases

Packages

Contributors

Languages