# Garmin Local MCP

Create and manage Garmin Connect workouts through an AI app that supports local
MCP servers. Runs on your computer, uses your own Garmin session, and exposes a
small set of tools rather than the full Garmin API.

**Status: local alpha.** Python 3.12, macOS and Linux. No Windows support, hosted
connector, or multi-user service in this release. This is an unofficial project,
not affiliated with Garmin. Garmin authentication and endpoints can change.

## What it does

- Preview structured workouts without login or uploading.
- Search Garmin's bundled strength exercise catalog.
- Read compact activity, workout-library and calendar summaries.
- Create, update in place, schedule and unschedule workouts when writes are enabled.
- Support timed warmups, left/right steps, supersets, exercise notes and rest timers.

Supports running, cycling, cardio and strength. Swimming/multisport are outside
v1. The pinned library says walking/hiking workout models cannot be uploaded.
Strength loads accept **pounds only** (`weight_lb`). Kilogram input is disabled
until the upstream representation is independently verified. Do not supply kg
values in the pound field.

## Install and connect

Install [uv](https://docs.astral.sh/uv/getting-started/installation/), download or
clone this repository, and enter its directory. Then:

```sh
uv sync --locked
uv run --locked garmin-mcp login
```

Enter your email, password and MFA code in the terminal, never in an AI chat.
Every interactive login authenticates a fresh session; it replaces any previous
local session only after successful authentication and saving. Each person
should use their own computer/user account or a separate private token directory.

Add the following to an AI client's **local MCP server** configuration, replacing
the command with the absolute path to your checkout:

```json
{
  "mcpServers": {
    "garmin-local": {
      "command": "/ABSOLUTE/PATH/garmin-local-mcp/.venv/bin/garmin-mcp",
      "args": ["serve"]
    }
  }
}
```

The client starts this process when it needs it. Preview and exercise search work
without login. There is no HTTP listener. This local process configuration is not
an installable phone connector; phone-only use needs a separately built remote
service or a supported connection to a running computer.

To enable writes, change the arguments to `["serve", "--allow-writes"]` and restart
the MCP connection. Configure your AI client to ask for approval for write calls.
The flag enables tools; it is **not per-call human approval**. Tool annotations
are hints and cannot enforce a client's approval UI.

Example prompt:

> Search for the exact Garmin names, then preview a strength workout with three
> sets of ten dumbbell rows per arm at 15 lb per dumbbell and 60 seconds rest after
> both arms. Wait for me to review before creating it.

Tokens are saved to `~/.local/share/garmin-local-mcp/garmin_tokens.json`. The parent
directory must be owned by you with mode 700 and the token file with mode 600.
Symlinks in the token path are rejected. Use `--token-dir /absolute/private/path`
on both `login` and `serve` for another location. Tokens are plaintext files
protected by permissions, not encrypted or stored in a system keychain.

## MCP tools

| Tool | Behavior |
| --- | --- |
| `preview_workout` | Validate/build a typed workout; return compact steps and totals without uploading |
| `search_exercises` | Search the bundled catalog for exact exercise names |
| `list_activities` | Paginated date, type, distance, duration, average HR and training effects |
| `list_workouts` | Paginated ID, name, sport and estimated duration |
| `list_scheduled_workouts` | Schedule and workout IDs over up to 31 days |
| `create_workout` | Write-enabled only: create a new `[AI]` workout |
| `update_workout` | Write-enabled only: replace an `[AI]` workout's complete definition while keeping its ID |
| `schedule_workout` | Write-enabled only: schedule an `[AI]` workout |
| `unschedule_workout` | Write-enabled only: verify the calendar entry and its `[AI]` workout, then remove the entry |

No delete, generic API, raw payload, filesystem or shell tools are exposed.
Read tools return summaries, not full workout definitions. The MCP write guard
requires a name beginning `[AI] `; this reduces accidental edits but is not proof
of ownership. Untagged workouts can be updated using the explicit saved-plan CLI
below. The tools do not push workouts to a watch: send them from Garmin Connect.

See [the exported tool schemas](docs/tool-schemas.json). Unknown inputs are
rejected. Repeats are one level deep, with at most 500 expanded steps. The local
validator's bounds do not guarantee a watch will accept every possible workout.

## Workout input

```json
{
  "workout": {
    "name": "Easy intervals",
    "sport": "running",
    "steps": [
      {"kind": "warmup", "duration_seconds": 300},
      {"kind": "repeat", "count": 3, "skip_last_rest": true, "steps": [
        {"kind": "interval", "distance_meters": 500,
         "target": {"kind": "pace_seconds_per_km", "low": 300, "high": 330}},
        {"kind": "recovery", "duration_seconds": 60}
      ]},
      {"kind": "cooldown", "duration_seconds": 300}
    ]
  }
}
```

Pace uses seconds/km (300 means 5:00/km). HR targets use `heart_rate_bpm` with
low/high values. Each executable step has exactly one of duration, distance, or
reps. Strength steps use an exact `exercise` name from search; add `weight_lb` and
`notes` as needed. Omit a load when unknown; zero is an explicit value.

Use notes to distinguish total weight, per dumbbell, per side, or added plate
weight. For unilateral exercises, use separate left/right steps with notes,
followed by one rest. A superset is a repeat group with both exercises and then
rest. `skip_last_rest` omits the group's final rest. Notes also support exercise
aliases when the catalog lacks an exact movement; the caller must review them.

Workout and step notes are preserved. There is no automatic weight progression.
Preview duration sums fixed-time steps and programmed rests, accounting for
skipped final rests. It excludes distance and repetition time, is marked partial
when appropriate, and supplies that partial value to Garmin's estimate field.

## Reusable saved plans

The [synthetic example](examples/saved-workout.json) demonstrates the plan format.
It is not a recommended training program and its ID is a placeholder.

```sh
mkdir -p private-workouts
cp examples/saved-workout.json private-workouts/my-workout.json
# Edit workout_id, expected_name and the complete workout definition.
# Obtain the actual ID/name using list_workouts or Garmin Connect.
uv run --locked python scripts/saved_workout.py private-workouts/my-workout.json
```

The command above only previews. After reviewing the plan, apply explicitly:

```sh
uv run --locked python scripts/saved_workout.py private-workouts/my-workout.json --apply
```

This CLI can update an existing untagged workout. It checks the exact ID, current
name and sport, preserves the name/ID, skips writes when the definition already
matches, and verifies the result. It replaces the full routine, not individual
steps. Never apply the example unchanged. Private routines are gitignored and
excluded from release archives. They still contain personal information: keep
local copies and backups private.

Reuse the saved workout each week; re-uploading is unnecessary. To change it,
edit the plan, preview, apply once, then send the updated version to your watch.
Calendar scheduling, recurring jobs, and automatic progression are not created
by this workflow.

## Security, reliability and verification

- Your AI provider receives the data returned by tools. Activity summaries omit
  GPS and account/profile fields. Treat Garmin text as data, not instructions.
- Logging goes to stderr; upstream Garmin response logging is suppressed and API
  errors are sanitized. No application payload logs or recordings are created.
- Tokens grant broader account access than the tool allowlist. Removing a local
  token file is not server-side revocation. See [SECURITY.md](SECURITY.md).
- Preview is a dry run, not an authorization token. Review actual write arguments.
- Calls are serialized. The wrapper does not retry writes. Upstream may refresh
  authentication and repeat a request rejected with 401. Network failures can
  occur after a write succeeds; inspect Garmin before repeating create/schedule.
- Unscheduling fails closed if it cannot identify the schedule's workout using
  `workoutScheduleId` and `workoutId`. That response shape still needs live testing.
- Login, creation, and in-place strength updates with pound values, timed steps,
  repeats, supersets and notes have been read-back verified on one account. Device
  display/execution, other accounts, running/cycling uploads, and scheduling are
  not comprehensively live-tested. Read-back does not prove watch compatibility.
- Offline tests use synthetic data and exercise validation, privacy filtering,
  write guards, token permissions and the real stdio protocol. CI does not contact
  Garmin. See [CONTRIBUTING.md](CONTRIBUTING.md) for commands.

The underlying API is provided by
[python-garminconnect](https://github.com/cyberjunky/python-garminconnect), with
[FastMCP](https://gofastmcp.com/) handling MCP. Runtime dependencies are pinned and
`uv.lock` captures the full environment. Review updates deliberately.

## License

[MIT](LICENSE). Dependency licenses remain their own.