# garmin-connect-workouts-mcp [Health: Active]

**Category:** 🏃 Sports  
**Repository:** https://github.com/slaat/garmin-connect-workouts-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 868  
**Views:** 7  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/garmin-connect-workouts-mcp

## Description
Turn plain language into real workouts on your Garmin watch: pace, HR, power, intervals, swim sets.

## Tools
Capabilities this server exposes over MCP:

- **create_garmin_workout** — Create a new structured workout in Garmin Connect from typed steps: durations, pace/HR/power/cadence targets, repeat blocks for intervals, and swim-specific stroke/equipment/pool-length fields. Use to add a workout; to change one that exists, use update_garmin_workout instead. Returns the new workoutId and a Connect link. Returns a re-auth message, not an exception, if no valid session exists. Example: [{kind:'step', intensity:'warmup', duration:{type:'time', value:10, unit:'min'}}, {kind:'repeat', iterations:5, steps:[...]}].
- **list_garmin_workouts** — List workouts stored in the Garmin Connect account, most recent first, with each workout's name, sport, and workoutId. Use this to find a workoutId to pass to get_garmin_workout, update_garmin_workout, delete_garmin_workout, or schedule_garmin_workout. Read-only. If no valid session exists, returns a message asking you to run authenticate_garmin rather than throwing.
- **get_garmin_workout** — Fetch the complete stored structure (all steps, targets, repeat blocks) of one workout by its workoutId, as raw JSON. Use this to inspect a workout, or to get its full contents before calling update_garmin_workout, which replaces the entire workout rather than patching it. Read-only. If no valid session exists, returns a message asking you to run authenticate_garmin rather than throwing.
- **update_garmin_workout** — Replace the entire contents (name, sport, steps, pool settings) of an existing workout, identified by workoutId, keeping its id. This is a full overwrite, not a partial patch - fields you omit are dropped. Call get_garmin_workout first to see the current contents before changing them. If no valid session exists, returns a message asking you to run authenticate_garmin rather than throwing.
- **delete_garmin_workout** — Permanently delete a workout from Garmin Connect by workoutId. This is irreversible - there is no undo or trash. Use list_garmin_workouts or get_garmin_workout first to confirm you have the right workoutId. If no valid session exists, returns a message asking you to run authenticate_garmin rather than throwing.
- **schedule_garmin_workout** — Put an existing workout on the Garmin Connect calendar for a specific date, so it appears as a planned session and can sync to a device. Requires a workoutId already created via create_garmin_workout or found via list_garmin_workouts - this tool does not create workouts. If no valid session exists, returns a message asking you to run authenticate_garmin rather than throwing.
- **check_garmin_auth** — Probe whether the stored Garmin Connect session is still valid, using a cheap authenticated request rather than a local expiry check (Garmin's session cookie does not carry a reliable expiry). Use this first when unsure whether the other tools will work. Returns a message telling you to run authenticate_garmin if the session is missing or has expired; never throws.
- **authenticate_garmin** — Authenticate with Garmin Connect by opening a real browser window at connect.garmin.com for you to log in normally, then capture and store only the resulting session cookies and CSRF token (never your password). Run this whenever check_garmin_auth reports no valid session, or any other tool returns its 'not authenticated' message. Requires a local display; will not work in a headless-only environment.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "garmin-connect-workouts-mcp": {
    "command": "npx",
    "args": ["-y","garmin-connect-workouts-mcp"]
  }
}
```

## Documentation

## What garmin-connect-workouts-mcp MCP server does

garmin-connect-workouts-mcp MCP server exposes Garmin Connect workout management through MCP tools. It can create workouts with ordered steps, target values, durations, and repeat blocks, then list existing workouts or retrieve the full structure of a selected workout.

The server also supports replacing an existing workout while retaining its identifier, deleting workouts, and placing workouts on the Garmin Connect calendar for a specified date. It covers running and cycling targets such as pace, heart rate, power, and cadence. Swim workouts can include stroke, equipment, and pool-length details.

The calling model supplies structured fields rather than asking the server to interpret an arbitrary text string. For example, a workout can represent a warmup, repeated intervals, recovery periods, and cooldown as separate typed steps. A pace supplied without both range boundaries is treated as the fast edge of a Garmin pace range, with the slow edge widened by 10 seconds.

## How it works

The MCP client invokes the available tools over a local server process. The server encodes the supplied workout structure into the format expected by Garmin Connect's web API. Repeat intervals are represented as repeat groups, allowing Garmin devices to show a repetition counter instead of receiving duplicated individual steps.

Garmin authentication relies on session cookies and a CSRF token. The server checks whether the stored session remains valid and can open a browser at Garmin Connect when login is required. After authentication, it stores the resulting session data locally rather than storing the Garmin password.

The project communicates with Garmin Connect's web API using requests based on the official web client's behavior. It is an unofficial integration, so changes to Garmin's web API may affect operation.

## Setup and configuration

For Claude Code, the documented setup is `claude mcp add garmin-workouts npx garmin-connect-workouts-mcp`. Claude Desktop can run it through an MCP configuration entry using the `npx` command and the package name, followed by a client restart.

The first authentication flow opens a real browser window for normal Garmin login. Session information is saved in `~/.config/garmin-connect-workouts-mcp/auth.json` with owner-only read and write permissions. The browser uses a separate persistent profile at `~/.config/garmin-connect-workouts-mcp/browser-profile/`, leaving the user's personal browser profile untouched.

When the stored session expires or is rejected, run `authenticate_garmin` again. `check_garmin_auth` can be used to test the current session. No environment variables are documented as required.

## Tools and capabilities

- `create_garmin_workout`: Creates a structured workout with steps, targets, and repeat groups.
- `list_garmin_workouts`: Lists workouts in the connected Garmin account.
- `get_garmin_workout`: Returns the complete structure of one workout.
- `update_garmin_workout`: Replaces an existing workout while preserving its ID.
- `delete_garmin_workout`: Removes a workout.
- `schedule_garmin_workout`: Adds a workout to the Garmin Connect calendar for a date.
- `check_garmin_auth`: Tests whether the saved Garmin session is still valid.
- `authenticate_garmin`: Starts browser-based Garmin authentication.

Targets include pace ranges, heart-rate zones or explicit beats-per-minute ranges, cycling power, and cadence. Swim steps can specify strokes such as freestyle, backstroke, breaststroke, butterfly, drill, or individual medley, along with equipment including fins, kickboards, paddles, pull buoys, and snorkels. Pool length can be expressed in meters or yards.

_Full upstream README: https://allmcps.com/mcp/garmin-connect-workouts-mcp/readme_