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, download or clone this repository, and enter its directory. Then:

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:

{
  "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

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. 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

{
  "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 demonstrates the plan format. It is not a recommended training program and its ID is a placeholder.

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:

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.
• 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 for commands.

The underlying API is provided by python-garminconnect, with FastMCP handling MCP. Runtime dependencies are pinned and uv.lock captures the full environment. Review updates deliberately.

License

MIT. Dependency licenses remain their own.