Skip to main content
Glama
smart-gym-mcp
by sla1k

smart-gym-mcp

Talk to your workouts. An MCP server that connects AI assistants like Claude to SmartGym on your Mac — so you can review your training, tweak routines, and build whole programs in plain English, and watch them sync to your iPhone and Apple Watch.

Why

SmartGym is a great workout tracker, but building and evolving a training program is still a lot of tapping. Meanwhile, AI assistants are genuinely good at programming workouts — they just had no way to reach your data.

This server bridges that gap. Your workout history, routines, and equipment become something you can have a conversation with:

  • "How has my bench press progressed over the last 3 months?"

  • "Add face pulls to my pull day, 3×12, after the rows."

  • "Build me a 3-day full-body comeback program based on what I was lifting in May, using only equipment I own."

Changes land in SmartGym itself — not a parallel app — so your data stays in one place and syncs everywhere via SmartGym's own engine.

Related MCP server: Garmin Connect MCP server

What it can do

Read — health check, list routines, routine detail split into warm-up / main / cool-down with recent sessions, workout history, your equipment.

Write — create programs with warm-up / main / cool-down, add / move / remove / reorder exercises, change sets / reps / weights / rest / notes, rewrite a whole routine in one call, archive / unarchive.

Safely — every write is a dry run first; applying snapshots the routine to ~/.smartgym-mcp/backups/, sends the change straight to SmartGym's server, re-reads it and verifies it. The SmartGym app keeps running and is never written to.

Connecting to your account

The MCP talks to SmartGym's own server with the session of the SmartGym app on your Mac. After installing (see Quick start), open SmartGym once so it syncs, then run:

smartgym-mcp auth

It finds the app's session, checks it with SmartGym's server and saves it to ~/.smartgym-mcp/credentials.json (mode 600) — never share that file. If macOS asks whether your terminal may access data from other apps, allow it. Run it again if tools report an authentication error.

Quick start

Requirements: macOS with SmartGym and uv.

Install a release from Releases as ~/.local/bin/smartgym-mcp:

uv tool install git+https://github.com/sla1k/smart-gym-mcp@v0.1.0

For a dev build of unreleased work, use @main or a commit SHA instead of the tag; its version reads X.Y.Z.devN. Run the command again with another ref to switch versions. Add the server to your MCP client — e.g. Claude Code:

claude mcp add -s user smartgym -- ~/.local/bin/smartgym-mcp

or Claude Desktop (claude_desktop_config.json; use the absolute path):

{
  "mcpServers": {
    "smartgym": { "command": "/Users/<you>/.local/bin/smartgym-mcp" }
  }
}

Then ask your assistant to call smartgym_health — { ok: true, ... } means you're connected, and version is the installed release. To run from a checkout instead, use uv run --directory /path/to/smart-gym-mcp smartgym-mcp as the command.

Configuration

Works out of the box with a standard SmartGym install. Env vars if you need them:

Var

Default

Purpose

SMARTGYM_CREDENTIALS

~/.smartgym-mcp/credentials.json

account session (see above)

SMARTGYM_BACKUP_DIR

~/.smartgym-mcp/backups

routine snapshots taken before each write

SMARTGYM_APP_BUNDLE

/Applications/SmartGym.app

exercise catalog and version check

SMARTGYM_APP_CACHE

SmartGym's Cache.db in its container

where smartgym-mcp auth finds the session

Contributing

Issues and PRs welcome. Design notes live in DESIGN.md, ideas in FEATURES.md.

uv run pytest                                  # tests never touch your real data
uv run ruff check src tests scripts/smoke_stdio.py && uv run mypy

Disclaimer

This is an unofficial, personal project — not affiliated with or endorsed by the makers of SmartGym. It uses SmartGym's private server API with your own account session; use at your own risk.

License

MIT

Available Tools

15 tools
smartgym_add_exerciseA
Destructive

Add a catalog exercise (built-in or custom) to a routine section (warmup / main / cooldown).

`position` counts within the section (0 = first; omitted = last). Optional rest,
note and template sets.

Inputs: routine (required), exercise (required), note, sets, +4 more. Returns: notice, changes, dry_run, routine, +2 more

smartgym_apply_routineB
Destructive

Rewrite a routine in one go (e.g. "week 2 of FB-A").

Each section you pass is the complete ordered list for that section: existing
exercises by exercise_id (optionally with new rest/note/sets), new ones by catalog
name (built-in or custom). An existing exercise listed under another section moves
there; one you leave out of a passed section is removed. Omitted sections stay as they
are.

Inputs: routine (required), days, goal, main, +5 more. Returns: notice, changes, dry_run, routine, +2 more

smartgym_archive_routinesA
DestructiveIdempotent

Archive routines (names or ids) on every device.

Reversible with smartgym_unarchive_routine.

Inputs: routines (required), dry_run. Returns: notice, dry_run, skipped, archived, +1 more

smartgym_create_programA
Destructive

Create one or more routines (a program) on the SmartGym server — all devices get them.

Each routine: name (must not match an active routine), goal (required free text, e.g.
"Strength" — the app can't save a routine without one), optional days/note, and three
ordered sections — `warmup` (optional), `exercises` (= main, required), `cooldown`
(optional). Each exercise: catalog name or id, optional rest_seconds, note and template
sets. Validation is all-or-nothing; dry_run=false creates the routines and verifies them
on the server.

Inputs: routines (required), dry_run. Returns: plan, notice, created, dry_run

smartgym_get_equipmentA
Read-only

List equipment (owned_only=true: only what you selected) plus dumbbell/kettlebell weights.

Inputs: owned_only. Returns: count, equipment, dumbbell_weights, kettlebell_weights

smartgym_get_routineA
Read-only

Get a routine split into warmup, main and cooldown sections.

Each exercise shows its exercise_id (what the edit tools take), rest, note, planned
template sets, and up to `history_depth` recent sessions (reps + weight_kg) with the
latest session's top set and total volume.

Inputs: routine (required), history_depth. Returns: days, goal, main, name, +5 more

smartgym_get_workout_historyA
Read-only

List past workouts (newest first) with duration, calories and heart rate.

Defaults to the last 7 days (or 14/30 via `days`); explicit `date_from` / `date_to`
(inclusive, local time) override it. Optional `routine` filter (name or id).
Paginated: total, has_more, next_offset.

Inputs: days, limit, offset, date_to, +2 more. Returns: count, total, offset, has_more, +2 more

smartgym_healthA
Read-only

Check the credentials file, the SmartGym server, and the installed app version.

ok=true means the server answered with your account data. `problem` explains
what to fix otherwise (e.g. create the credentials file). `data_as_of` is the server's
last-modified time of the account data, in local time with its UTC offset — older than
the last workout on the iPhone means the app hasn't synced yet. `warning` appears when the installed SmartGym version
differs from the one the MCP was verified against.

Inputs: no named parameters. Returns: ok, problem, version, warning, +4 more

smartgym_list_routinesA
Read-only

List routines: id, name, days, and exercise counts per section (warm-up/main/cool-down).

Archived routines are listed only with include_archived=true. Use the id (or the
name) in the other tools.

Inputs: include_archived. Returns: count, routines

smartgym_move_exerciseA
DestructiveIdempotent

Move an exercise to another section (or to another position in its section).

`position` counts within the target section (0 = first; omitted = last).

Inputs: section (required), exercise_id (required), dry_run, position. Returns: notice, changes, dry_run, routine, +2 more

smartgym_remove_exerciseB
Destructive

Remove an exercise from its routine (logged history is kept).

Inputs: exercise_id (required), dry_run. Returns: notice, changes, dry_run, routine, +2 more

smartgym_reorder_routineA
DestructiveIdempotent

Reorder exercises inside sections.

Each list you pass must hold exactly that section's current exercise_ids, in the new
order; omitted sections stay as they are. To change an exercise's section use
smartgym_move_exercise.

Inputs: routine (required), main, warmup, dry_run, +1 more. Returns: notice, changes, dry_run, routine, +2 more

smartgym_unarchive_routineC
DestructiveIdempotent

Bring an archived routine back to the active list.

Inputs: routine (required), dry_run. Returns: notice, dry_run, skipped, archived, +1 more

smartgym_update_exerciseC
DestructiveIdempotent

Change an exercise's rest time, note ("" clears) or template sets.

`sets` is the FULL planned list [{reps, weight_kg}] — sets beyond it are removed,
extra ones added.

Inputs: exercise_id (required), note, sets, dry_run, +1 more. Returns: notice, changes, dry_run, routine, +2 more

smartgym_update_routineA
DestructiveIdempotent

Edit a routine's name, days, goal or note (only the fields you pass; "" or, for days, [] clears).

The goal can be changed but not cleared (the app can't save a routine without one).
A new name must not match another active routine. dry_run=false snapshots the
routine, sends the edit, and verifies it on the server.

Inputs: routine (required), days, goal, name, +2 more. Returns: notice, changes, dry_run, routine, +2 more

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 15 tools

    Disambiguation3/5

    Most tools target distinct resource+action pairs, but the exercise-editing cluster overlaps heavily: smartgym_apply_routine is effectively a superset of add_exercise, remove_exercise, move_exercise and reorder_routine, and move vs reorder differ only subtly. Descriptions do explicitly cross-reference each other (e.g. reorder tells you to use move_exercise for section changes), which mitigates but does not eliminate the misselection risk.

    Naming Consistency4/5

    All tools use a consistent snake_case smartgym_ verb_noun pattern, making the set highly predictable. Minor deviations: create_program creates routines (resource name differs from the rest of the tool set), and archive_routines is plural while unarchive_routine is singular.

    Tool Count4/5

    15 tools sits at the upper edge of a well-scoped set but each operation corresponds to a real editing primitive in the fitness-routine domain (create, update, section edits, ordering, archiving). Given the redundant apply_routine covers several of the granular tools, the count could plausibly be trimmed, but it is not excessive.

    Completeness4/5

    The routine lifecycle is well covered: list/get, create, update metadata, archive/unarchive, full exercise CRUD within sections, and bulk rewrite. Gaps are minor and mostly read-only: no hard delete of a routine, no custom-exercise creation in the catalog, and workout history is list-only with no per-workout detail or logging.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects AI assistants to Arvo fitness coach for tracking workouts, PRs, body progress, and training splits through natural conversation.
      16 npm
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to access and modify a user's real GymTimer workout and nutrition data stored in private iCloud, allowing natural-language queries about training history and the creation of workout templates and meal plans.
      21
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Connects AI assistants directly to Hevy workout data, enabling analysis of training volume, strength progression tracking, and web searches for fitness research.
      MIT