smart-gym-mcp
smart-gym-mcp lets an AI assistant read and safely modify your SmartGym routines and workout data, with changes synced through SmartGym’s own server.
Check connection health, credentials, installed app version, and account data.
List routines (including archived) and view routine details split into warm-up/main/cool-down with recent session history, top sets, and volume.
Review workout history with date/routine filters and pagination, plus equipment and available dumbbell/kettlebell weights.
Create full programs/routines with warm-up, main, and cool-down sections, including exercises, sets, reps, weights, rest, notes, days, and goals.
Edit routine metadata; add, move, remove, reorder, or update exercises; rewrite a whole routine in one call.
Archive and unarchive routines.
Stay safe: writes are dry-run by default, snapshots are taken before applying, and changes are re-read and verified on SmartGym’s server.
Targets the Apple ecosystem by way of SmartGym: routines and programs created, edited, or built through the tools sync through SmartGym's own engine to the user's iPhone and Apple Watch, so training plans are available on Apple devices.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@smart-gym-mcp How has my bench press progressed over the last 3 months?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 authIt 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.0For 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-mcpor 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 |
|
| account session (see above) |
|
| routine snapshots taken before each write |
|
| exercise catalog and version check |
| SmartGym's | where |
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 mypyDisclaimer
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
Available Tools
15 toolssmartgym_add_exerciseADestructive
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_routineBDestructive
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_routinesADestructiveIdempotent
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_programADestructive
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_equipmentARead-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_routineARead-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_historyARead-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_healthARead-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_routinesARead-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_exerciseADestructiveIdempotent
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_exerciseBDestructive
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_routineADestructiveIdempotent
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_routineCDestructiveIdempotent
Bring an archived routine back to the active list.
Inputs: routine (required), dry_run. Returns: notice, dry_run, skipped, archived, +1 more
smartgym_update_exerciseCDestructiveIdempotent
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_routineADestructiveIdempotent
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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Connect ChatGPT or Claude to your Gym Plus account to log and review workouts with AI coaching.
Your strength-training data for any AI assistant: workouts, progress, muscle volume, routines.
Log workouts and meals by telling your AI. 873 exercises, muscle diagrams, food lookup.
Your Garmin, Oura, WHOOP, Hevy and 35 more fitness apps, queryable from your own AI.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceConnects AI assistants to Arvo fitness coach for tracking workouts, PRs, body progress, and training splits through natural conversation.16 npm3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to design strength training workouts, push them to Garmin Connect and your watch, and read back completed sessions and exercise history.MIT
- AlicenseAqualityCmaintenanceEnables 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.21MIT
- AlicenseNot gradedqualityCmaintenanceConnects AI assistants directly to Hevy workout data, enabling analysis of training volume, strength progression tracking, and web searches for fitness research.MIT