garmin-mcp

Personal MCP server for interacting with your Garmin Connect data.

Exposes 62 tools across 11 domains — activities, health, body composition, training, workouts, nutrition, profile, extras, stats, write, and workout write — via the Model Context Protocol over stdio transport. Works with Claude Desktop, VS Code / GitHub Copilot, Cursor, OpenCode, and any other MCP-compatible AI client.

Security & credentials

Read this before you do anything else.

Your Garmin email and password are used exactly once — during the one-time garmin-mcp-auth setup step — to authenticate with Garmin's servers over HTTPS. They are never written to disk, never logged, and never stored anywhere by this software.

What is stored afterward is a small OAuth token file managed by the garminconnect library:

~/.garminconnect/<user_id>/garmin_tokens.json

That file contains exactly three fields:

No email address. No password. No display name. No health data. The file lives outside your project folder and cannot accidentally be committed to git.

This repo contains no hardcoded credentials, no telemetry, and no outbound network calls except directly to Garmin Connect's own servers.

Related MCP server: Garmin MCP Server

Requirements

• Python 3.11+

• uv package manager

• A Garmin Connect account

Setup

1. Install uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
(Invoke-WebRequest -Uri https://astral.sh/uv/install.ps1 -UseBasicParsing).Content | powershell -c -

2. Clone and install dependencies

git clone https://github.com/gabecorsini/garmin-mcp.git
cd garmin-mcp
uv sync

3. Authenticate with Garmin Connect (one-time)

uv run garmin-mcp-auth

You will be prompted for your Garmin email, password, and MFA code (if enabled). Tokens are saved to ~/.garminconnect/<user_id>/garmin_tokens.json and refreshed automatically on subsequent runs.

4. Verify the server starts

uv run python -m garmin_mcp

You should see: [garmin-mcp] Connected to Garmin Connect as: <your display name>

Press Ctrl+C to stop.

MCP client configuration

Replace /absolute/path/to/garmin-mcp (or the Windows equivalent) with the actual path to your cloned repo in every snippet below.

Claude Desktop

Config file locations:

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

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "garmin": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/garmin-mcp",
        "python",
        "-m",
        "garmin_mcp"
      ]
    }
  }
}

VS Code / GitHub Copilot

VS Code uses a different key ("servers", not "mcpServers").

Workspace config — create .vscode/mcp.json in your project:

{
  "servers": {
    "garmin": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/garmin-mcp",
        "python",
        "-m",
        "garmin_mcp"
      ]
    }
  }
}

User profile config — open the Command Palette, run MCP: Open User Configuration, and add the same block.

Cursor

Global config file: ~/.cursor/mcp.json
Project-level config file: .cursor/mcp.json

{
  "mcpServers": {
    "garmin": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/garmin-mcp",
        "python",
        "-m",
        "garmin_mcp"
      ]
    }
  }
}

OpenCode

Config file: ~/.config/opencode/opencode.json

OpenCode requires the command to be an array (not a string + args object). Use the full path to your uv executable.

{
  "mcpServers": {
    "garmin": {
      "command": [
        "/path/to/uv",
        "run",
        "--directory",
        "/absolute/path/to/garmin-mcp",
        "python",
        "-m",
        "garmin_mcp"
      ]
    }
  }
}

Find your uv path with which uv (macOS/Linux) or (Get-Command uv).Source (Windows PowerShell).

OpenCode agent

A ready-made agent definition is provided at agents/garmin.md. Copy it to your OpenCode agents folder:

# macOS / Linux
cp agents/garmin.md ~/.config/opencode/agents/garmin.md

# Windows (PowerShell)
Copy-Item agents\garmin.md "$env:USERPROFILE\.config\opencode\agents\garmin.md"

Once installed, OpenCode will load the Garmin-specific context and guidance automatically when you start a conversation with the garmin agent. The agent knows all 62 tool names, understands when data might not be available (older devices, non-running activities, etc.), and provides examples for common queries.

Available tools

Activities (9)

Health & Wellness (13)

Body Composition (3)

Training & Performance (8)

Workouts (2)

Nutrition (3)

Profile & Devices (7)

Extras (6)

Stats (5)

Write — Health (3)

Write — Workouts (3)

Notes

• Unofficial API: This server uses the reverse-engineered Garmin Connect API via python-garminconnect (MIT) and garmin-health-data (Apache 2.0). Garmin does not provide an official public API. Use at your own risk.

• Garmin ToS: Automated access to Garmin Connect is a gray area. This tool is intended for personal, non-commercial use only. Do not use it in ways that could disrupt Garmin's services.

• Rate limits: Garmin may throttle or block excessive API calls. Avoid tight loops over large date ranges.

• Token refresh: Tokens are refreshed automatically. If authentication fails after an extended period, re-run garmin-mcp-auth.

• Data availability: Not all tools return data for all devices or activity types. Metrics like VO2 max, race predictions, lactate threshold, and HRV require a compatible Garmin device (e.g. Forerunner, Fenix, Venu series).

• Not supported: The Lifestyle Journal (mood, energy, symptoms, menstrual cycle logging) is not exposed by any known API endpoint in python-garminconnect and cannot currently be read or written by this server.

License

MIT — Gabe Corsini, 2026