durely garmin-insights-mcp

Ask your AI assistant about your own Garmin data: your full training history, health and recovery, analysed.

durely insights is an MCP server that connects your Garmin Connect account to your AI assistant (Claude, Cursor, GitHub Copilot, Gemini CLI, Codex or any other MCP client) through Garmin's official Personal API. It keeps a copy of your history on your own machine, so you can ask about a single run or about years of training and get an answer right away.

Early development. Everything below works, but tools and options can still change before version 1.0.

Unofficial project: not affiliated with or endorsed by Garmin.

What you can ask

Activities

• "What did I do this week?" / "Show my last 10 runs"
• "Tell me about yesterday's run": splits, heart rate, training effect, load
• "How did my power and heart rate evolve over the intervals of Tuesday's ride?"
• "Compare the bike legs of my last two triathlons lap by lap"
• "Am I getting fitter on my regular Tuesday run?"

Training

• "How has my training load and fitness developed over the last 3 months?"
• "Analyse Saturday's ride: time in zones, decoupling, best efforts"
• "How many kilometres did I run, ride and swim per year?"

Health and recovery

• "How did I sleep this week, and how was my HRV?"
• "Does a hard training day affect my HRV the next morning?"
• "Compare my resting heart rate and sleep score per month this year"
• "Show my heart rate and Body Battery through yesterday"

What makes it different

• Official API, no password. It uses a Personal API key that you create in Garmin Connect and can revoke at any time. No scraping, nothing that breaks when Garmin changes its login.
• Your whole history, instantly. Everything is synced once to a local database and kept up to date, so trend questions over months or years don't wait on Garmin.
• Second-by-second detail. Laps, swim lengths, heart rate, power, cadence and more come from each activity's original FIT file, including VO2max, recovery time and lactate threshold when your device records them.
• Analysis built in. Time in zones, training load and fitness/fatigue/form, aerobic decoupling, best efforts, recovery trends and comparisons of similar sessions. For anything else, your assistant can run read-only SQL over your data.
• Private by default. Your data stays on your machine. Your name, account ID and GPS positions are kept out of answers unless you ask for a route.
• Read-only. It can't change anything in your Garmin account.

Quick start

You need Garmin Connect, an MCP client (Claude Code, Claude Desktop, Cursor, …) and either Node.js 24+ or Docker.

1. Create your Personal API key

1. In Garmin Connect on the web, open Settings → Personal API Token.

2. Create a key and pick how long it stays valid (30 days to 1 year). Garmin shows it only once, so copy it.

3. Save it by running this in your own terminal:

   npx -y @durely/garmin-insights-mcp auth
   

   It asks for the key (your input stays hidden), checks it with Garmin and saves it to ~/.config/garmin/connect-personal-api-key, readable only by you. If Garmin rejects the key, nothing is saved. The server reads the key from this file, so it doesn't go in your client config.

   With Docker (no Node.js), save it to that file yourself:

   mkdir -p ~/.config/garmin && chmod 700 ~/.config/garmin
   pbpaste > ~/.config/garmin/connect-personal-api-key    # macOS; elsewhere, paste it into this file with an editor
   chmod 600 ~/.config/garmin/connect-personal-api-key
   

Don't paste the key into a chat with your AI assistant.

2. Choose how to run it

With Node.js (npx): nothing to install. Your server command is:

npx -y @durely/garmin-insights-mcp

npx downloads the npm package on first use and picks up new releases by itself. Check your key with npx -y @durely/garmin-insights-mcp auth --check. Prefer a fixed install? npm install -g @durely/garmin-insights-mcp gives you the garmin-insights command.

Or with Docker (no Node.js needed; Docker must be running). Your server command is:

docker run -i --rm \
  -v ~/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro \
  -v garmin-mcp-data:/data \
  -e GARMIN_MCP_TIMEZONE=Europe/Brussels \
  ghcr.io/durely/garmin-insights-mcp

Replace Europe/Brussels with your own time zone. To check your key, run the same command with auth --check at the end. The image runs on Intel and ARM (Apple silicon, Raspberry Pi). More Docker tips are in How it works.

Or from source: clone the repo and build it with npm or Docker. See How it works.

Updating: with npx, restart your client. With Docker, run docker pull ghcr.io/durely/garmin-insights-mcp. Your synced data is kept.

3. Add it to your AI client

Claude Code:

claude mcp add garmin --scope user -- npx -y @durely/garmin-insights-mcp

With Docker:

claude mcp add garmin --scope user -- docker run -i --rm \
  -v ~/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro \
  -v garmin-mcp-data:/data \
  -e GARMIN_MCP_TIMEZONE=Europe/Brussels \
  ghcr.io/durely/garmin-insights-mcp

--scope user makes it available in all your projects.

Claude Desktop: open Settings → Developer → Edit Config, add this, and restart Claude Desktop:

{
  "mcpServers": {
    "garmin": {
      "command": "/opt/homebrew/bin/npx",
      "args": ["-y", "@durely/garmin-insights-mcp"]
    }
  }
}

Desktop apps don't see your shell's PATH, so use the full path to npx (find it with which npx). If the log then says node isn't found, add "env": { "PATH": "/opt/homebrew/bin:/usr/bin:/bin" }, with the folder from which node first.

{
  "mcpServers": {
    "garmin": {
      "command": "/usr/local/bin/docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/Users/you/.config/garmin/connect-personal-api-key:/run/secrets/garmin_api_key:ro",
        "-v",
        "garmin-mcp-data:/data",
        "-e",
        "GARMIN_MCP_TIMEZONE=Europe/Brussels",
        "ghcr.io/durely/garmin-insights-mcp"
      ]
    }
  }
}

{
  "servers": {
    "garmin": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@durely/garmin-insights-mcp"]
    }
  }
}

gemini mcp add garmin npx -- -y @durely/garmin-insights-mcp

codex mcp add garmin -- npx -y @durely/garmin-insights-mcp

4. Try it

Start a new session and ask: "Check my Garmin connection." It should report connected.

The first question starts a sync in the background. Your activities are there within seconds; the rest of your history follows in a few minutes. After that, the data refreshes automatically when it's more than an hour old.

Good to know

• Keep your key's expiry date in mind. Garmin's API doesn't tell the server when your key expires. Set GARMIN_API_KEY_EXPIRES (e.g. 2027-10-24) in your client config and garmin_status reminds you in time. With Docker, pass it to the container instead: add -e GARMIN_API_KEY_EXPIRES=2027-10-24 to the docker run arguments. Replacing the key file is enough; no restart is needed.
• Sync at least every few months. Garmin deletes intraday detail (heart rate through the day, overnight HRV readings) after about 4–5 months. Whatever the server has synced stays in your local copy.
• Desktop and CLI clients only, for now. The server runs on your own machine, so it doesn't work in claude.ai on the web or mobile yet.
• Your data goes to your AI client. The server only talks to Garmin, but the answers it gives go to the MCP client and model you use.

Troubleshooting

Tools

You don't need to call these yourself; your assistant picks them. For reference:

In clients that support prompts (often as slash commands), weekly_review, activity_deep_dive and recovery_check start a guided analysis.

Configuration

All optional; set them as environment variables in your client config.

In Docker, the key file and data directory are /run/secrets/garmin_api_key and /data.

Privacy and security

• Your key stays on your machine. It's exchanged for a 24-hour token, cached with owner-only permissions. The server never writes the key itself. To revoke access, delete the key in Garmin Connect.
• No telemetry. The server only talks to Garmin's Personal API.
• Your synced data is sensitive. The local database and FIT files hold your health and activity history, including GPS tracks. The data directory is readable only by you (in Docker it lives in the garmin-mcp-data volume).
• Identity and location stay out of answers. Your name, profile picture and account ID are removed before anything is stored. GPS positions are only returned when you ask for route or location analysis (or query an activity's start and end point with SQL).

More

• How it works: the local cache and sync, FIT files, how the numbers are calculated, Docker details, development

License

Apache-2.0. See LICENSE and NOTICE.

Data provided by Garmin devices via Garmin Connect; the analyses are insights derived in part from Garmin device-sourced data. Garmin and Garmin Connect are trademarks of Garmin Ltd. or its subsidiaries. This project is not affiliated with or endorsed by Garmin.