Garmin MCP Server
The Garmin MCP Server exposes Garmin Connect wellness and recovery metrics to AI assistants, enabling health-aware workload planning. Key capabilities include:
Daily Wellbeing Snapshot: Get a concise overview of sleep, Body Battery, HRV, stress, Training Readiness, and a workload recommendation for a given date.
Workload Guard: Evaluate a proposed workload (with optional ticket/task count) against current recovery signals and receive a safety assessment with a suggested safer daily scope when metrics are poor.
Sleep Summary: Fetch focused sleep metrics including score, duration, overnight HRV, sleep stress, Body Battery change, and resting heart rate for a specific date.
Training Load Trends: View 7-day vs. 28-day trends for key recovery metrics like sleep, HRV, stress, Training Readiness, and Body Battery.
Personal Baselines: Compute personal baseline ranges for recovery metrics over a historical window.
Change Alerts: Detect meaningful daily changes such as sleep drops, HRV dips, stress spikes, or readiness declines.
Token-Based Auth: Cache Garmin session tokens locally to avoid repeated logins.
All tools default to today's date if none is provided (use YYYY-MM-DD format), and integrate with any MCP-compatible assistant such as Claude Desktop.
Provides tools for fetching daily wellbeing snapshots (sleep, Body Battery, HRV, stress, Training Readiness, training status) from Garmin Connect, evaluating workloads against recovery signals, and summarizing sleep/recovery context.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Garmin MCP Server check my Garmin wellbeing snapshot for today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Tool | Description |
| Returns 7-day versus 28-day trends for sleep, HRV, stress, training readiness, and Body Battery at wake. |
| Computes personal baseline ranges for recovery metrics over a historical window. |
| Highlights meaningful daily changes such as sleep drops, HRV dips, stress spikes, and readiness declines. |
| Returns a concise daily snapshot with recovery metrics and workload recommendation. |
| Evaluates a proposed workload against current Garmin recovery signals. |
| Returns focused sleep and recovery context for a given date. |
MCP Resource
Resource | Description |
| Today's wellbeing snapshot as JSON. |
MCP Prompt
Prompt | Description |
| Instructions for using Garmin context during workload planning. |
Installation
npm install
npm run buildAuthentication
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 loginThe login command:
Prompts for your Garmin email.
Prompts for your Garmin password without echoing it to the terminal.
Authenticates with Garmin Connect.
Creates the token cache directory if it does not exist.
Writes reusable Garmin session tokens to
.garmin-tokensby 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 .envExample .env:
GARMIN_TOKEN_DIR=.garmin-tokens
GARMIN_IS_CN=falseSupported variables:
Variable | Purpose |
| Directory used to read/write Garmin session tokens. Defaults to |
| Set to |
| Optional email used by |
| Optional password used by |
| Compatibility alias for |
| Compatibility alias for |
| Compatibility password option. The value is decoded from base64 before login. |
| Compatibility alias for |
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 startnpm 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_trendgarmin_baseline_profilegarmin_change_alertsgarmin_wellbeing_snapshotgarmin_workload_guardgarmin_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 loginagain if tokens become stale.
If the MCP client cannot fetch Garmin data:
Confirm
npm run buildhas been run anddist\\index.jsexists.Use an absolute
GARMIN_TOKEN_DIRin the MCP client config.Confirm the MCP client was restarted after config changes.
Run
npm run loginagain if Garmin has invalidated the session.
If TypeScript build fails:
npm install
npm run typecheck
npm run buildRecommended 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 buildSecurity
Do not commit
.envor token cache directories.Prefer token reuse over repeated credential logins.
Treat all Garmin data as private health-related context.
Available Tools
3 toolsgarmin_sleep_summaryGarmin sleep summaryB
Fetch Garmin sleep score, duration, overnight HRV, sleep stress, Body Battery change, and resting heart rate.
Inputs: date.
garmin_wellbeing_snapshotGarmin wellbeing snapshotB
Fetch a concise Garmin Connect wellbeing snapshot for a date: sleep, Body Battery, HRV, stress, training readiness, and a workload recommendation.
Inputs: date, includeRaw.
garmin_workload_guardGarmin workload guardA
Check Garmin recovery metrics before committing to a workload and suggest a safer daily scope when signals are weak.
Inputs: workload (required), ticketCount, date.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
The sleep_summary and wellbeing_snapshot tools overlap significantly, as wellbeing_snapshot includes sleep data and more. An agent may be unsure which to use for sleep metrics alone, though descriptions help differentiate scope.
All tools follow a consistent 'garmin_<area>_<descriptor>' pattern using underscores. While not verb_noun, the naming is predictable and readable.
Three tools is slightly low for a comprehensive health tracking server, but the set covers key recovery and readiness metrics without being trivial.
The tools focus on sleep, wellbeing, and workload recovery but lack common Garmin features like activity logs, steps, or heart rate trends, creating notable gaps.
Maintenance
Related MCP Connectors
Garmin watch data for AI assistants: activities, sleep, HRV, recovery. Never writes to Garmin.
Garmin data in Claude & ChatGPT via the Garmin Health API. OAuth sign-in, no password sharing.
Unofficial Garmin Connect access: sleep, HRV, training, activities, workouts and weight.
Apple Health training load, recovery, HRV and workout detail for Claude, ChatGPT and any MCP client.
Related MCP Servers
- AlicenseBqualityBmaintenanceLocal-first MCP server that connects AI agents to your Garmin sleep, HRV, Body Battery, stress, training readiness and activities, keeping tokens on your machine.242261 npm13MIT
- AlicenseNot gradedqualityDmaintenanceExposes personal Garmin wellness data through MCP tools for accessing summary, sleep, HRV, heart rate, stress, body battery, and historical data.MIT
- AlicenseAqualityDmaintenanceExposes WHOOP recovery, sleep, strain, and workout metrics to MCP-compatible AI assistants using OAuth 2.0 authentication, enabling daily wellbeing snapshots, trend analysis, and workload recommendations.6ISC
- AlicenseBqualityCmaintenanceExposes personal Garmin Connect data to MCP-capable clients like Claude and Gemini. Enables querying daily stats, heart rate, sleep, activities, and managing workouts.16MIT