smart-gym-mcp
# smart-gym-mcp
**Talk to your workouts.** An [MCP](https://modelcontextprotocol.io) server that connects AI
assistants like Claude to [SmartGym](https://smartgym.app) 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.
## 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:
```sh
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`](https://docs.astral.sh/uv/).
Install a release from [Releases](https://github.com/sla1k/smart-gym-mcp/releases) as
`~/.local/bin/smartgym-mcp`:
```sh
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:
```sh
claude mcp add -s user smartgym -- ~/.local/bin/smartgym-mcp
```
or Claude Desktop (`claude_desktop_config.json`; use the absolute path):
```json
{
"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`](DESIGN.md), ideas in
[`FEATURES.md`](FEATURES.md).
```sh
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](LICENSE)
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.