Skip to main content
Glama

garmin-mcp

CI License: MIT

A personal, self-hosted remote MCP server for Garmin Connect. You deploy it to your own Vercel account for your own Garmin account, then connect it to Claude, ChatGPT, Cursor or any other MCP client. The assistant can then read your activities, sleep, HRV, Body Battery, training readiness and training calendar, and, if you allow it, create workouts on your watch. It is free, open source and runs on the free tiers of Vercel and Upstash.

Status: early. The unit and tool tests run against a mocked Garmin API, and the project is new. It has not been battle-tested against real accounts over a long period, and Garmin's private API can change without notice. See the disclaimer.

What you can ask

  • "How recovered am I today? Should I do the intervals on my calendar or take it easy?"

  • "Review my last week of training. Did I do too much?"

  • "Is my resting heart rate trending up over the last month, and how is my HRV baseline?"

  • "Compare my last three long runs. Did my heart rate drift in the second half?"

  • "Build me a 10 x 400 m workout at 4:00 per km with 90 seconds of jog recovery and put it on my watch for Thursday." (needs write tools)

  • "How many kilometres are on my road shoes, and are my race predictions improving?"

Related MCP server: Garmin Health MCP Server

Features

  • Composite tools get_daily_briefing and get_weekly_review answer broad questions in one call instead of a dozen.

  • Compact output. Garmin's large JSON responses are trimmed to the fields that matter, so they use fewer tokens.

  • Structured workout creation: describe warm-up, intervals, repeats and targets, and the server builds the Garmin workout and can schedule it.

  • A raw garmin_api_get tool as an escape hatch for read-only endpoints that have no dedicated tool.

  • Garmin session tokens are stored encrypted (AES-256-GCM) in Upstash Redis and refreshed automatically.

  • Built-in MCP prompts for a daily check-in, a weekly review and race readiness.

  • Write tools are off by default and must be enabled explicitly.

Quick start

You need a Vercel account, a GitHub account and a computer with uv installed.

1. Deploy to Vercel

Deploy with Vercel

Vercel asks for MCP_AUTH_TOKEN. This is the secret that protects your endpoint. Generate one with:

openssl rand -hex 32

Keep a copy. You need it again for the login script and for your MCP client. It must be at least 24 characters long.

2. Add Upstash Redis and redeploy

In your Vercel project, open the Storage tab, add Upstash for Redis from the Marketplace, and connect it to the project. Vercel injects KV_REST_API_URL and KV_REST_API_TOKEN. Then redeploy so the new variables take effect.

Without Redis the server keeps tokens in memory only and loses them whenever the function restarts.

You can check the deployment at https://<app>.vercel.app/api/health. It reports whether the secret is configured, whether storage is redis or memory, and whether write tools are enabled. It never returns secrets or Garmin data.

3. Log in to Garmin from your own computer

Garmin's login cannot run on Vercel. Cloudflare bot protection blocks datacenter IP addresses and non-browser TLS clients. So you log in once on your own machine, and the script uploads the resulting session tokens to your server.

Clone the repository (or download scripts/garmin_login.py) and run:

uv run scripts/garmin_login.py --url https://<app>.vercel.app

The script prompts for your Garmin email, your Garmin password, an MFA code if your account uses one, and your deployment's MCP_AUTH_TOKEN. Your Garmin password goes only to Garmin. The server receives the session tokens, checks them against Garmin, and stores them encrypted.

From then on the server refreshes the tokens itself. Run the script again only if a tool reports that the Garmin session is no longer valid.

The script also reads GARMIN_EMAIL, GARMIN_PASSWORD, MCP_AUTH_TOKEN and GARMIN_MCP_URL from the environment if you prefer not to type them.

4. Connect a client

Pick the endpoint style your client supports. See Connecting clients.

Connecting clients

There are two ways to authenticate.

  • Secret in the URL: https://<app>.vercel.app/api/mcp/<MCP_AUTH_TOKEN>. Use this for clients that only accept a URL, such as Claude custom connectors and ChatGPT. Treat this URL as a password.

  • Bearer header: https://<app>.vercel.app/api/mcp with the header Authorization: Bearer <MCP_AUTH_TOKEN>. Use this where the client lets you set headers.

Claude

Open Settings, then Connectors, then Add custom connector. Paste the URL that includes your secret.

ChatGPT

Add a custom connector (MCP) in the connector or developer settings and paste the URL that includes your secret. The exact menu names depend on your plan and change over time.

Claude Code

claude mcp add --transport http garmin https://<app>.vercel.app/api/mcp --header "Authorization: Bearer <token>"

Cursor

Add this to mcp.json:

{
  "mcpServers": {
    "garmin": {
      "url": "https://<app>.vercel.app/api/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Other clients

Any client that supports the Streamable HTTP transport works with either endpoint style.

Tools

All tools are read-only unless marked as write. Dates are YYYY-MM-DD in your timezone and default to today. Garmin units are passed through: distances in metres, durations in seconds, speeds in metres per second, weight in grams.

Insights

Tool

Description

get_daily_briefing

Training readiness, last night's sleep, HRV status, wellness totals, training status, the last 3 days of activities and the next 2 days of scheduled workouts, in one call.

get_weekly_review

A 7-day review: every activity with load and training effect, weekly totals by sport, daily sleep, HRV, resting heart rate, stress and readiness series, and the current training status.

Activities

Tool

Description

list_activities

Recorded activities, newest first, with distance, duration, heart rate, pace or speed, power, training effect and load. Filterable by activity type.

get_activity

Full detail for one activity: summary metrics, splits, time in heart-rate and power zones, weather and strength sets. Choose sections with include.

get_activity_timeseries

Sampled heart rate, speed, cadence, power and elevation over time for one activity, for pacing and drift analysis.

Health

Tool

Description

get_daily_summary

One day's wellness totals: steps, distance, floors, calories, heart rate, stress, Body Battery, intensity minutes, SpO2 and respiration.

get_sleep

Sleep for the night ending on a date: stages, sleep score and sub-scores, overnight HRV, respiration, SpO2 and sleep need.

get_hrv

Overnight HRV: last-night average, weekly average, personal baseline range and HRV status.

get_stress

Stress level for a day, with the intraday curve in timeseries mode.

get_body_battery

Body Battery per day over a range: charged, drained, highs, lows and the events behind them.

get_heart_rate

All-day heart rate: resting, 7-day average resting, minimum and maximum, with the intraday curve in timeseries mode.

get_respiration_and_spo2

Breathing rate and blood oxygen saturation for a date.

get_health_trends

Daily values of one or more metrics over a date range (sleep, HRV, resting heart rate, stress, Body Battery, steps, intensity minutes, respiration, training readiness, VO2 max).

get_weight

Weigh-ins over a range, with body composition when a smart scale recorded it.

get_blood_pressure

Blood pressure readings logged in Garmin Connect over a range.

get_hydration

Fluid intake against the daily goal, including estimated sweat loss.

Training

Tool

Description

get_training_readiness

Training Readiness score for a date with the factors behind it and Garmin's feedback.

get_training_status

Status label, acute and chronic load and their ratio, load focus balance, VO2 max and acclimation.

get_fitness_metrics

VO2 max, fitness age, endurance score, hill score, lactate threshold and cycling FTP in one call.

get_race_predictions

Predicted finish times for 5K, 10K, half marathon and marathon, current or as a trend over a range.

get_training_zones

Heart-rate zones per sport and power zones configured in Garmin Connect.

get_personal_records

Personal records held in Garmin Connect.

get_training_load

Per-activity training load and training effect over a range, for load progression and ramp analysis.

Planning

Tool

Description

get_calendar

Scheduled workouts, races, other calendar events and the active training plan. Defaults to the next 14 days.

list_workouts

Structured workouts saved in your Garmin Connect library.

get_workout

The full step-by-step structure of a saved workout.

create_workout

Write. Create a structured workout, optionally scheduling it on a date so it syncs to the watch.

schedule_workout

Write. Put an existing saved workout on the calendar for a date.

unschedule_workout

Write, destructive. Remove one scheduled occurrence from the calendar. The workout stays in the library.

delete_workout

Write, destructive. Permanently delete a saved workout and its calendar entries.

The four write tools are registered only when GARMIN_ENABLE_WRITE=true.

Profile

Tool

Description

garmin_status

Checks that the server can reach your Garmin account: whether tokens are stored, when the session expires, and the account name.

get_profile

Your profile and settings: height, weight, measurement system, sleep schedule, lactate threshold and primary activity types.

get_devices

Registered devices with model, software version, primary training device and last sync.

get_gear

Shoes, bikes and other gear with total distance and activity count.

garmin_api_get

Escape hatch: a read-only GET against any Garmin Connect API path when no dedicated tool covers it.

Prompts

Prompt

Description

daily_checkin

How recovered you are today and what today's training should look like.

weekly_review

Review the last 7 days and plan the next week.

race_readiness

Assess readiness for a race you name, with an optional goal, and suggest pacing.

Configuration

Set these in your Vercel project (Settings, Environment Variables). .env.example lists the same variables.

Variable

Required

Default

Description

MCP_AUTH_TOKEN

Yes

none

Secret that protects the MCP endpoint and the token upload endpoint. At least 24 characters. Generate with openssl rand -hex 32. It also derives the token encryption key.

KV_REST_API_URL

Yes, in practice

none

Upstash Redis REST URL. Injected by Vercel when you connect Upstash for Redis. UPSTASH_REDIS_REST_URL is also accepted.

KV_REST_API_TOKEN

Yes, in practice

none

Upstash Redis REST token. Injected by Vercel. UPSTASH_REDIS_REST_TOKEN is also accepted.

GARMIN_TIMEZONE

No

Europe/Lisbon

IANA timezone used to resolve "today". Set this to your own.

GARMIN_ENABLE_WRITE

No

false

Set to true to expose the tools that create, schedule, unschedule and delete workouts.

GARMIN_TOKENS

No

none

Fallback when no Redis is configured: the contents of garmin_tokens.json (raw JSON or base64). Refreshed tokens then stay in memory only. You can produce the value with uv run scripts/garmin_login.py --print.

Redis is marked "yes, in practice" because the server starts without it, but tokens are then lost on every restart.

Local development

Requires Node.js 20 or newer.

npm install
cp .env.example .env.local

Edit .env.local and set at least MCP_AUTH_TOKEN. Then start the dev server:

npm run dev

Run the tests and the type check:

npm test
npm run typecheck

To try the server interactively, start the dev server and run the MCP Inspector:

npx @modelcontextprotocol/inspector

Point it at http://localhost:3000/api/mcp using the Streamable HTTP transport, with the header Authorization: Bearer <your MCP_AUTH_TOKEN>.

To log in against a local server, use --url http://localhost:3000:

uv run scripts/garmin_login.py --url http://localhost:3000

Without Redis configured, tokens are held in the memory of the dev server process.

Security and privacy

What is stored and where:

  • Your Garmin session tokens (not your password) are stored in your own Upstash Redis database, encrypted with AES-256-GCM. The key is derived from MCP_AUTH_TOKEN, so a leaked Redis database alone does not give access to your Garmin account.

  • Garmin data is fetched on demand and returned to your MCP client. The server does not store it.

  • Your Garmin password is never sent to the server. The login script sends it only to Garmin.

  • Whatever your MCP client sends to its model provider includes the Garmin data it requested. Check your client's privacy settings.

The endpoint secret:

  • Anyone with MCP_AUTH_TOKEN can read your Garmin data through the server, and change it if write tools are enabled. The URL form https://<app>.vercel.app/api/mcp/<MCP_AUTH_TOKEN> contains the secret, so treat it like a password. Do not paste it into public places, screenshots or shared chats.

  • The token upload endpoint (/api/admin/tokens) accepts the secret only in the Authorization header, never in the URL.

  • Secrets in URLs can appear in logs of proxies and clients. Prefer the bearer header when your client supports it.

To rotate the secret:

  1. Generate a new value with openssl rand -hex 32.

  2. Update MCP_AUTH_TOKEN in the Vercel project and redeploy.

  3. Run the login script again. The stored tokens were encrypted with a key derived from the old secret and can no longer be read.

  4. Update the URL or header in every MCP client.

Leave GARMIN_ENABLE_WRITE off unless you want the assistant to change your calendar and workout library. The create and delete tools ask the assistant to confirm with you first, but that is a request to the model, not a guarantee.

To report a vulnerability, see SECURITY.md.

Troubleshooting

A tool reports an authentication error. Ask your client to run garmin_status. It reports whether tokens are stored, when the session expires and whether Garmin accepts them. If the session is invalid, run uv run scripts/garmin_login.py --url https://<app>.vercel.app again.

The client gets 401 from the endpoint. The secret in the URL or header does not match MCP_AUTH_TOKEN. If you changed the variable, redeploy and update the client. A 503 response means MCP_AUTH_TOKEN is missing or shorter than 24 characters.

Garmin returns 403. Garmin is refusing the request. Either the account does not have that feature, or Garmin is blocking the server's network. If it happens on every call, wait and retry later, then run the login script again. The server cannot work around Garmin's network blocking.

Tokens disappear after a while. Redis is probably not connected. Open /api/health and check that storage is redis. If it says memory, connect Upstash for Redis in the Vercel Storage tab, redeploy, and run the login script again. Also check that you did not change MCP_AUTH_TOKEN.

Rate limiting (429). Garmin limits request rates, including token refreshes. Wait a few minutes and retry. Prefer get_daily_briefing and get_weekly_review, or get_health_trends over a range, instead of many per-day calls.

Responses are slow or time out. Requests have a 60 second limit. Narrow the date range, or request summary instead of timeseries where a tool offers both.

A metric is empty. Garmin returns no data when your watch does not record it or you did not wear it. Tools return "No data recorded in Garmin Connect for this request."

Disclaimer

This project uses Garmin Connect's private, unofficial API, the same one the Garmin mobile app uses. It follows the maintained Python library python-garminconnect 0.3.x. It is not affiliated with, endorsed by or supported by Garmin. Garmin can change or block this API at any time, which may break the server until it is updated. It is meant for accessing your own data from your own account. Check Garmin's terms of service and use it at your own risk.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

Licence

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Personal MCP server for interacting with your Garmin Connect data. Exposes 62 tools across 11 domains including activities, health, training, and workouts.
      1
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      A local MCP server that exposes Garmin Connect activity, health, and training data as tools for Claude Desktop. It provides read-only access to metrics like activities, sleep, heart rate, and training readiness.
      25
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to read Garmin Connect data — sleep, heart rate, stress, HRV, body composition, activities, steps, training status/readiness and VO2max trends — through a read-only set of 14 MCP tools. It also generates visualized daily and weekly health reports as Markdown or self-contained HTML+SVG, with credential redaction, dual auth modes, and a mock mode for testing without a real account.
      1
      MIT