Garmin MCP Server

Garmin MCP Server exposes Garmin Connect wellness and recovery metrics to MCP-compatible AI assistants. It helps agents incorporate sleep, recovery, and training context when planning work.

Capabilities

• Fetch daily wellbeing snapshots from Garmin Connect

• Summarize sleep, Body Battery, HRV, stress, Training Readiness, and training status

• Analyze short-term versus long-term recovery trends

• Compute personal baseline ranges over historical windows

• Highlight meaningful changes versus yesterday and baseline

• Recommend an appropriate workload level from current recovery signals

• Provide a guardrail tool for assistants before accepting heavy workloads

• Cache Garmin session tokens locally to avoid repeated logins

Related MCP server: health-mcp

MCP Tools

MCP Resource

MCP Prompt

Installation

npm install
npm run build

Authentication

The recommended local setup is an interactive one-time login. This writes Garmin session tokens to disk so the MCP server can run later without storing your Garmin password.

Run:

npm run login

The login command:

1. Prompts for your Garmin email.

2. Prompts for your Garmin password without echoing it to the terminal.

3. Authenticates with Garmin Connect.

4. Creates the token cache directory if it does not exist.

5. Writes reusable Garmin session tokens to .garmin-tokens by default.

Your password is used only for the login request. It is not written to disk.

After a successful login you should see output similar to:

Garmin MCP login
This creates a reusable local token cache. Your password is not written to disk.

Garmin email: you@example.com
Garmin password:

Login successful for Your Name.
Token cache written to C:\path\to\garmin-mcp-server\.garmin-tokens.
You can now use the Garmin MCP server without storing your Garmin password.

The MCP server loads tokens from GARMIN_TOKEN_DIR. If the variable is not set, it uses ./.garmin-tokens relative to the directory where the server process starts.

For MCP clients, prefer passing an absolute GARMIN_TOKEN_DIR in the client configuration. This avoids issues when the client starts the server from a different working directory.

Environment Variables

Create a local environment file only if you want to customize settings:

Copy-Item .env.example .env

Example .env:

GARMIN_TOKEN_DIR=.garmin-tokens
GARMIN_IS_CN=false

Supported variables:

For local development, use npm run login instead of keeping GARMIN_PASSWORD in .env. Credentials in environment variables are mainly useful for non-interactive or temporary automation.

Verify the Server Locally

After logging in and building, run:

npm run typecheck
npm run build
npm run start

npm run start launches the MCP server over stdio. It will wait for an MCP client to speak the protocol, so it may appear idle in a normal terminal. That is expected.

Claude Desktop Configuration

Add the server to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "garmin": {
      "command": "node",
      "args": ["C:\\path\\to\\garmin-mcp-server\\dist\\index.js"],
      "env": {
        "GARMIN_TOKEN_DIR": "C:\\path\\to\\garmin-mcp-server\\.garmin-tokens"
      }
    }
  }
}

Replace C:\\path\\to\\garmin-mcp-server with the absolute path where you cloned the project.

You can also place GARMIN_EMAIL and GARMIN_PASSWORD in the env block instead of using token login, but token login is preferred for local machines because it does not require storing the Garmin password in the MCP client config.

After editing the MCP client configuration, restart the client so it reloads the server definition.

Codex Configuration Example

If your MCP client uses a TOML-style server config, the same setup looks like this:

[mcp_servers.garmin]
command = "node"
args = ["C:\\path\\to\\garmin-mcp-server\\dist\\index.js"]

[mcp_servers.garmin.env]
GARMIN_TOKEN_DIR = "C:\\path\\to\\garmin-mcp-server\\.garmin-tokens"

Restart Codex after updating the config. Once loaded, the Garmin tools should be available as MCP tools:

• garmin_training_load_trend

• garmin_baseline_profile

• garmin_change_alerts

• garmin_wellbeing_snapshot

• garmin_workload_guard

• garmin_sleep_summary

Troubleshooting

If login fails:

• Confirm the email and password work in Garmin Connect in a browser.

• If your account uses Garmin China, set GARMIN_IS_CN=true.

• Delete the token cache and run npm run login again if tokens become stale.

If the MCP client cannot fetch Garmin data:

• Confirm npm run build has been run and dist\\index.js exists.

• Use an absolute GARMIN_TOKEN_DIR in the MCP client config.

• Confirm the MCP client was restarted after config changes.

• Run npm run login again if Garmin has invalidated the session.

If TypeScript build fails:

npm install
npm run typecheck
npm run build

Recommended Agent Guidance

Use Garmin context as part of planning, especially when I propose a heavy workload, late-day push, risky refactor, production change, or many tickets in one day.

Before agreeing to heavy work, call garmin_workload_guard or garmin_wellbeing_snapshot.

If sleep, Body Battery, HRV, stress, or Training Readiness are poor, push back concretely: reduce ticket count, split the work, defer risky items, and create a stopping point.

Do not moralize or diagnose health. Treat the metrics as planning context, not medical advice.

If Garmin data is unavailable, say that plainly and fall back to normal workload planning.

Development

npm run dev
npm run login
npm run typecheck
npm run build

Security

• Do not commit .env or token cache directories.

• Prefer token reuse over repeated credential logins.

• Treat all Garmin data as private health-related context.