openGym MCP
An MCP server for workout tracking: Claude Desktop, Cursor and Cline read routines, sets, body weight and 1RM from your self-hosted openGym
- 17,207 ★ on the repository
- Last commit
- AGPL-3.0
Extended access
Why this level
- Reads health data: body weight and training history from your openGym instance files
- A local Node process gets access to the data folder and runs dependencies from npm install; the server uses no network
Install
- Works in
Manual install
git clone https://github.com/DuarteSantos8/openGym && cd openGym/mcp && npm installThe server lives in the repository's mcp folder and has no package in the npm registry. openGym itself runs separately with docker compose up -d.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Reads health data: body weight and training history from your openGym instance files
- A local Node process gets access to the data folder and runs dependencies from npm install; the server uses no network
This is third-party code. Review the repository files before installing.
What it does
openGym MCP is an MCP server for workout tracking that lives in the `mcp/` folder of the openGym tracker repository and answers questions about your training. A client such as Claude Desktop starts it as a local stdio process, the server reads the `state-<uid>.json` files from the `./data` folder of your openGym instance and returns the data as JSON. The server only reads; this version has no writing tools. There are nine tools: `list_routines` and `get_routine` show routines and per-exercise prescriptions, `preview_session` shows what the app would put on screen when a workout starts after the progression rules apply, `get_week_plan` gives the next seven days, `list_workouts` and `get_workout` return sessions and a set-by-set breakdown, `get_bodyweight` returns weigh-ins and the gap to the goal, `estimate_1rm` computes the best estimated one-rep max and its trend, and `muscle_balance` ranks muscles by load and flags neglected ones. The numbers come from the same pure functions in `frontend/src/lib/` that draw the Stats screen, so the agent's answer about your bench press matches the app. Set, date and level labels are pre-formatted into readable text in `src/labels.js`, so the agent does not have to decode them.
Who it is for. For people who log workouts in a self-hosted openGym and want to ask an AI assistant about progress, training load and the weekly plan.
Good fit when
- You want to ask the assistant for your estimated bench press 1RM and how it moved over recent months
- Before a workout you want to know which weight the app will propose: `preview_session` shows it after the progression rules, not from the saved routine
- You want to see which muscles stayed undertrained this week or month and get advice on the routine
- You want to compare body weight with the goal line and see the gap as a number without opening the app
Not a fit when
- You want the agent to log workouts or body weight or edit routines: the author has postponed writing tools to a later phase
- You do not run a self-hosted openGym: the server reads files from the instance's `./data` folder and does not connect to other servers or a cloud
- The app runs on a different machine than the client, or you need HTTP access: the server reads the data folder directly, and the HTTP transport is planned only for the third phase
- The machine has no Node.js or cannot run `npm install`: the server depends on the MCP SDK and zod packages
Example request
What is my estimated bench press 1RM and how has it changed over the last three months? And which muscles did I undertrain this week?MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
OPENGYM_DATA- Path to the data folder of the openGym instance the server reads state files from
OPENGYM_UID- Profile id from data/db.json, needed when there are several users
Limitations
- The server runs from source: you need a clone of the repository, `npm install` in the `mcp/` folder and Node.js. It is not part of the Docker image.
- Version 0.1.0 only reads data. Logging workouts and weight and editing routines are planned for a second phase, together with an access token issued from the admin dashboard.
- The server sees one user per launch. With a single profile it finds that user itself; with several, set `OPENGYM_UID`: the id sits in `./data/db.json` under `users`.
- The openGym tracker itself, according to its author, is largely written in Claude Code. The training logic is covered by tests, and the server in the `mcp/` folder has its own 58 cases on the demo data.
- The license is AGPL-3.0-or-later. The exercise media in the app carry a separate license and are not part of the server.
How to disable. Remove the `opengym` block from `mcpServers` in the client settings and restart the client. The server writes nothing and does not run in the background: it exits when the client closes the connection. The `mcp/` folder with dependencies stays in the repository clone and can be deleted.
FAQ
How do I connect Claude Desktop to the openGym workout tracker?
Run `npm install` in the `mcp/` folder, then add an `opengym` server to `claude_desktop_config.json` with the command `node`, the path to `mcp/src/index.js` and an `OPENGYM_DATA` variable pointing to the `data` folder. After the client restarts, the server's stderr prints a line naming the profile it serves.
How is `get_routine` different from `preview_session`?
`get_routine` returns what the routine stores. `preview_session` shows what the app will put on screen at start: progression rules and history can raise or lower the weight. A routine holding squat 3×8 at 60 kg opens at 75 kg after progression, so name a weight from the `preview_session` reply.
Can the assistant log a workout or body weight through MCP?
No. Version 0.1.0 has nine tools and all of them read. Logging workouts and weight and editing routines are planned for a second phase, which needs an access token from the admin dashboard and a write lock so it does not clash with the web UI.
Does the assistant see passkeys and session secrets?
No. The server reads only the `state-<uid>.json` files with training data. Passkey private keys stay on your device, and the VAPID keys and the session signing secret live in other files that are never passed to the assistant. The server makes no network requests and sends no telemetry.
How do I find out which muscles are undertrained?
Call `muscle_balance`: it ranks muscles by load for the week, the month or all time and names the neglected ones separately. The app shows the same calculation on its muscle map, so the numbers in chat and on screen match.
Discussion
No questions or reviews yet.
Related
MCP serversStrava MCP
Strava MCP Server
Strava MCP server: an agent reads your workouts, heart rate, power, segments and routes and exports routes to GPX and TCX
Garmin MCP
garmin-mcp
Garmin Connect data for an agent: activities, health, editing names and notes. Works through the unofficial python-garminconnect library
Hevy MCP
hevy-mcp
Hevy workout data for an agent: programs, exercise templates, folders. An API key is needed and is available only with paid Hevy PRO
YouGile MCP
Yougile MCP Server
MCP server for YouGile: projects, boards, columns, tasks, users and task chats from the agent
Google Calendar MCP Server: calendar for Claude
Google Calendar MCP Server
A calendar MCP for Claude Desktop: the agent views, creates, updates and deletes Google Calendar events, recurring ones included
yougile-mcp
@nebelov/yougile-mcp
An MCP server for the YouGile task tracker covering API v2: projects, boards, tasks, chats, users, stickers and webhooks
README in short
The repository front page describes the whole tracker: a weekly plan over a library of more than 5,600 exercises, weight suggestions with progression rules, stats, passkey sign-in, imports from FitNotes, Strong and Hevy, and 19 languages. The quick start comes down to `docker compose up`. A separate `mcp/README.md` describes the server: installation, client registration, a table of nine tools, the plan for phases two and three and the test suite.