garmin-health-mcp

An MCP server that gives Claude (or any MCP client) your Garmin data — sleep, HRV, resting heart rate, Body Battery, stress, calories, activities, training load and recovery — through Garmin's official Personal API, launched on 21 October 2026. No password scraping, no reverse-engineered endpoints: you create a personal API key in Garmin Connect, and this server uses it read-only.

On top of the raw data it keeps a local history so it can do the things the API doesn't:

• Time series and charts for ~45 daily metrics, with rolling averages and trends.

• Training load the way Garmin shows it: acute load, chronic load and their ratio (with Garmin's 0.8–1.5 optimal band), plus fitness / fatigue / form (CTL / ATL / TSB) and an approximate Load Focus.

• A readiness estimate built like Garmin's Training Readiness (sleep, recent sleep, HRV status, recovery time, acute load, recent stress) that calibrates to your watch as you log Garmin's scores.

• Dashboard-ready data and a built-in prompt for building an interactive dashboard artifact.

Unofficial project, not affiliated with or endorsed by Garmin. "Garmin" is a trademark of Garmin Ltd.

What you need

1. A Garmin account with a Personal API key (it starts with GCDC_). Create one in Garmin Connect's settings under the Personal API / Connect Developer Program Personal tier. Keys last a year; only one can exist at a time.

2. uv (the installers below use it to run the server).

Related MCP server: garmin-mcp

Install

Claude Desktop (one click)

Download garmin-health-mcp.mcpb from the latest release and open it. Claude Desktop asks for your API key and stores it in the OS keychain.

Claude Code (plugin)

/plugin marketplace add jonpojonpo/garmin-health-mcp
/plugin install garmin-health@garmin-health-mcp

Claude Code asks for your API key when the plugin is enabled and keeps it in your system keychain. You can also leave it empty and provide the key as GARMIN_API_KEY, or in the file Garmin's own client uses:

mkdir -p ~/.config/garmin && printf '%s' 'GCDC_...' > ~/.config/garmin/connect-personal-api-key
chmod 600 ~/.config/garmin/connect-personal-api-key

The plugin also installs three skills (see Skills).

OpenAI Codex CLI

codex mcp add garmin-health -- uvx --from git+https://github.com/jonpojonpo/garmin-health-mcp garmin-health-mcp

Put the key in ~/.config/garmin/connect-personal-api-key as above, or add --env GARMIN_API_KEY=GCDC_... before the -- (that stores it in plain text in ~/.codex/config.toml). The first start downloads the dependencies; if Codex reports a startup timeout, add startup_timeout_sec = 60 under [mcp_servers.garmin-health] in ~/.codex/config.toml.

ChatGPT (web and app) only connects to MCP servers over the internet, so it needs a hosted or tunnelled copy of the server; that isn't packaged yet.

Any MCP client

{
  "mcpServers": {
    "garmin-health": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jonpojonpo/garmin-health-mcp", "garmin-health-mcp"],
      "env": { "GARMIN_API_KEY": "GCDC_..." }
    }
  }
}

The first call backfills 210 days of history (about 35 API requests); after that only stale days are fetched. Call sync(days=365) for a longer history.

Tools

Prompts: Morning briefing, Weekly review, Build a dashboard.

Skills

Tools fetch the data; skills tell Claude what to do with it. They ship with the Claude Code plugin, and the folders in skills/ can also be added to Claude Desktop or claude.ai as custom skills.

Models and how far to trust them

Garmin's Personal API does not expose Training Readiness, Training Status, recovery time, acute load or Load Focus (those paths return 404). This server models them from the data that is exposed, and the constants were fitted against the Garmin Connect app's own screens for one rider on 25 October 2026:

One rider is not a validation set. Readiness corrects itself per user: log Garmin's score with log_garmin_readiness (or just tell Claude the number) and it applies an offset, then a fitted slope once four scores are logged. If your numbers drift from Garmin's in other places, please open an issue with both values.

Privacy

Your data goes only between your computer and Garmin's API. The API key is read from the environment (Claude Desktop keeps it in the OS keychain) or from a local file, and is never logged or returned by a tool. The short-lived access token and the history database live in ~/.garmin-health-mcp/ (override with GARMIN_HEALTH_DATA_DIR). Delete that folder to remove everything. Whatever your MCP client does with tool results (for example, sending them to a model) follows that client's own privacy terms.

Other Personal API servers

Garmin's Personal API is new and several community servers appeared within days. If you only want the raw endpoints, Mason-Levyy/garmin-personal-mcp wraps all of them one-to-one; braydenabo/garmin-mcp keeps a local archive with trends and charts; zigmund/garmin-papi-mcp is a remote server with OAuth for claude.ai and ChatGPT. This project focuses on the layer on top: training load, recovery, a calibrated readiness estimate, and a one-click Claude Desktop install.

Development

uv sync
uv run pytest
uv run ruff check
GARMIN_API_KEY=GCDC_... uv run garmin-health-mcp   # stdio server
npx @anthropic-ai/mcpb pack                        # build the .mcpb bundle

Endpoint list and the key-to-token exchange follow Garmin's own reference client, garmin-connect-personal-api-python, as documented in cluffa/garmin-api-cli.

License

MIT