Garmin Personal MCP

Ask your AI about your Garmin data, on Garmin's official API.

Quickstart · Tools · Authentication · Changelog

Garmin Personal MCP is a free, open-source MCP server that connects your Garmin Connect account to Claude, Cursor, VS Code, or any other MCP client. Ask about last night's sleep, HRV trends, Body Battery, stress, training load, weight, or a specific run, all from your real Garmin account. It runs on Garmin's official Personal API with a revocable key, so it never needs your Garmin password, and it's read-only.

Published on PyPI as garmin-personal-mcp and in the official MCP Registry as io.github.Mason-Levyy/garmin-personal-mcp.

Unofficial project, official API. This isn't made by Garmin, but it only talks to Garmin's documented Personal API through Garmin's own Python client.

How is this different from other Garmin MCP servers?

Most Garmin MCP servers sign in with your Garmin password through the unofficial garminconnect library, which breaks whenever Garmin changes its login. In October 2026 Garmin opened a Personal API for individuals. This server uses it:

• No password, no scraping: a revocable Personal API key you create in Garmin Connect, exchanged for short-lived tokens
• The whole Personal API: every working endpoint in Garmin's reference has a tool, with every documented filter
• Any date range: ranges longer than an endpoint allows (28 days for steps, 31 for sleep, and so on) are split into requests for you
• Model-sized responses: all-day sample arrays are left out unless you ask for them
• Read-only: the Personal API can't change your account, and neither can this server

Quickstart

1. Save your Personal API key (one-time; see Authentication):

   uvx garmin-personal-mcp auth
   

2. Add the server to your client. The install buttons at the top do this in one click for Cursor and VS Code.

   Claude Code

   claude mcp add garmin -- uvx garmin-personal-mcp
   

   Or install it as a plugin, which asks for your key in place of step 1:

   /plugin install garmin-personal-mcp --marketplace Mason-Levyy/garmin-personal-mcp
   

   Claude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json), and Cline (cline_mcp_settings.json) all take the same entry:

   {
     "mcpServers": {
       "garmin": {
         "command": "uvx",
         "args": ["garmin-personal-mcp"]
       }
     }
   }
   

   VS Code (or use the button above):

   code --add-mcp '{"name":"garmin","command":"uvx","args":["garmin-personal-mcp"]}'
   

   Codex CLI:

   codex mcp add garmin -- uvx garmin-personal-mcp
   

   Gemini CLI:

   gemini mcp add garmin uvx garmin-personal-mcp
   

3. Ask it something: "how did I sleep last night?", "is my HRV trending down this month?", "compare my last three long runs".

Requires uv. Any MCP client that speaks stdio or streamable HTTP works, not just Claude.

Finding this useful? A ⭐ on GitHub helps other Garmin users find it.

Authentication

1. Sign in to Garmin Connect on the web and open Settings → Personal API.
2. Create a key and choose how long it lasts (30 days to a year). Garmin shows it once.
3. Run garmin-personal-mcp auth and paste it at the hidden prompt. The server checks it with Garmin before saving it to ~/.config/garmin/connect-personal-api-key with owner-only permissions.

Where there's no terminal to prompt in (a script, or a shell an agent runs), pipe the key in instead, e.g. pbpaste | garmin-personal-mcp auth.

garmin-personal-mcp auth --check reports whether the saved key still works, without prompting. Garmin emails you about a week before a key expires: create a new one and run auth again. No restart is needed; the server reads the key on every call.

Instead of the key file you can set GARMIN_PERSONAL_API_KEY, which takes precedence. The key file and bearer-token cache are the same ones Garmin's gc-personal CLI uses, so a key saved by either works for both.

Docker Compose

Run the server as a background HTTP service using the prebuilt image. Save this as compose.yaml:

services:
  garmin:
    image: ghcr.io/mason-levyy/garmin-personal-mcp:latest
    command: ["--http", "--host", "0.0.0.0"]
    environment:
      - GARMIN_PERSONAL_API_KEY
    ports:
      - "127.0.0.1:8491:8491"
    volumes:
      - garmin-config:/home/garmin/.config/garmin
      - ./downloads:/home/garmin/Downloads/garmin
    restart: unless-stopped

volumes:
  garmin-config:

latest is the newest release, the same version PyPI serves. To stay on one version, use a version tag such as :0.2.0 instead.

From the directory containing compose.yaml, create the downloads folder and pull the image:

mkdir -p downloads
docker compose pull

Activity files from garmin_download_activity land in ./downloads. The tool reports the path inside the container (/home/garmin/Downloads/garmin/...), which is the same file. The container runs as uid 1000, so on Linux, if your uid isn't 1000, run sudo chown 1000 downloads.

Don't mount an existing ~/.config/garmin from the host into the container. The key file there is readable only by its owner, so the container can't read it unless your uid is 1000. Use one of the options below instead.

The container paths above and uid 1000 stay the same across releases.

Authentication

Choose one of these authentication options:

1. Add your API key to a .env file

Create .env next to compose.yaml and add your Personal API key:

GARMIN_PERSONAL_API_KEY='your-personal-api-key'

Compose loads this file automatically. You do not need to run auth.

2. Use the interactive auth command

Leave GARMIN_PERSONAL_API_KEY unset in your shell and .env, then run:

docker compose run --rm garmin auth

Paste your Personal API key at the prompt. It is saved for subsequent starts.

Start the server

docker compose up -d

In your MCP client, add a Streamable HTTP server with the URL http://127.0.0.1:8491/mcp.

The server only accepts requests addressed to 127.0.0.1 or localhost, and it has no authentication. To reach it from another machine, keep the port on 127.0.0.1, put an authenticating proxy or tailnet in front (see Remote / HTTP mode), and add the hostname clients use to command:

    command: ["--http", "--host", "0.0.0.0", "--allowed-host", "garmin.example.ts.net"]

Without --allowed-host, requests to any other hostname are rejected.

Build from source

Clone the repository and use compose.yaml in its root, which builds the image from source. From the repository directory, run:

docker compose build

Then follow the authentication and startup steps above. After updating the source, rebuild and restart with:

docker compose up --build -d

Tools

All tools take dates as YYYY-MM-DD. Range tools default to the 7