Docs
Gymus MCP server
Gymus runs a remote MCP server at https://api.gymus.app/mcp. Connect it to ChatGPT, Claude or another MCP client and sign in with Google. The assistant can then read your training history and, when you ask, log or change workouts, plans, weigh-ins and exercise notes.
By Gymus · Published
- Server URL
https://api.gymus.app/mcp- Transport
- Streamable HTTP
- Sign-in
- OAuth 2.1 with PKCE, through your Google account
- Tools
- 19: 9 read, 4 add, 3 change, 3 delete
- Rate limit
- 60 tool calls per minute per account
- Units
- kilograms, metres and centimetres; times in ISO 8601, UTC
Connect an assistant
Sign in with the Google account you use in the Gymus Android app, so the assistant sees your workouts. Any other Google account opens a new, empty Gymus account.
- ChatGPT: install the Gymus plugin. The ChatGPT plugin guidehas the steps for phone and web.
- Claude on the web, desktop or mobile: open Settings → Connectors, choose Add custom connector, enter
https://api.gymus.app/mcp, then connect. - Claude Code: run the command below, then type
/mcpin Claude Code and choose gymus to sign in. - Other MCP clients: any client that supports Streamable HTTP and OAuth can connect with the server URL. It finds the sign-in page from the server's OAuth metadata, so there is no client ID or secret to copy.
claude mcp add --transport http gymus https://api.gymus.app/mcpHow sign-in works
Gymus has no password of its own. You sign in with Google, and Gymus gives the assistant its own tokens.
- The assistant asks the server where to sign in, then registers with Gymus's authorization server, using a Client ID Metadata Document or Dynamic Client Registration.
- Your browser opens Google's sign-in. Gymus asks Google only for your basic profile and email address, to find your Gymus account. Gymus never sees your Google password.
- Gymus shows a consent screen that names the assistant asking for access. Choose Approve.
- Gymus gives the assistant an access token and a refresh token. The access token works only on
https://api.gymus.app/mcpand expires after 1 hour. The assistant uses the refresh token to get a new pair, and each refresh token expires 30 days after it was issued.
A few things follow from this:
- Every tool reads and changes only the Gymus account of the Google account you signed in with. No tool can reach another person's data.
- Access is all or nothing: Gymus has no separate permissions for reading and writing. To limit what an assistant does, use its own tool settings. Claude, for example, asks before each call to a tool that changes data unless you allow it.
- The access token is signed, not encrypted. It carries the Google profile you signed in with (your name, email address and profile picture), so the assistant can read those too.
- MCP tokens are signed with a key of their own, so an assistant's token can't be used to sign in to the Gymus app, and the app's sign-in can't be used on the MCP server.
Tools
The server has 19 tools. Weights go in and out in kilograms, distances in metres and heights in centimetres. The assistant converts them to the units you read, which get_training_profile reports. Workouts include average and maximum heart rate, but never the heart-rate readings behind them.
Read: 9 tools that change nothing
The assistant calls these on its own when your question needs them.
list_workouts- Your most recent workouts, newest first, up to 50 per call, optionally between two dates. Each has its name, start time, duration, plan, exercises, number of working sets, average and maximum heart rate if a watch recorded it, and its AI analysis score.
get_workout- One workout in full: every exercise in order with its muscle and equipment, and every set with its type, reps, weight, time or distance, reps in reserve, and when in the session it was done.
list_workout_plans- Your workout plans as summaries: name, whether Gymus generated it, expected duration, exercises and last edit.
get_workout_plan- One plan in full: exercises in order, prescribed sets, rest times and supersets.
get_schedule- When you train: a rotation of plans, or a plan for each weekday.
get_training_profile- Your training profile: current, starting and target weight, height, date of birth and age, gender, goal, experience level, equipment, days per week, session length, split, focus muscle groups, any limitations or injuries you entered, language, and the units you prefer to read.
list_weight_records- Your weigh-ins, newest first, up to 365.
get_exercise_notes- Your notes on exercises ("seat at 4"), most recently edited first, up to 500.
search_exercises- Finds exercises by name, muscle or equipment in the Gymus catalog and in the custom exercises you created, up to 30 matches. The assistant needs it to get the exercise IDs that logging takes. Catalog names are in English.
Add: 4 tools that write new records
These add to your account and overwrite nothing, with one exception (an exercise note). The assistant should check the details with you before it calls them.
log_workouts- Logs up to 20 workouts in one call: name, start time, duration, the plan followed, and each exercise's sets with reps, weight, time or distance, set type and reps in reserve. Either all of them are saved or none is.
create_workout_plans- Adds up to 10 workout plans: exercises in order, prescribed sets, rest, supersets and expected duration. All or none.
log_weight_records- Logs up to 100 weigh-ins with their dates. The newest becomes the current weight in your training profile. A wrong weigh-in can only be corrected or deleted in the app.
add_exercise_note- Adds a note to an exercise that has none. An exercise has at most one note. If you wrote a note on your phone that hasn't synced yet, this one replaces it.
Change: 3 tools, preview first
Each change shows you a preview and needs your OK before anything is written (see below).
update_workout- Corrects a workout's name, start time, duration, plan, or its exercises and sets. Changing the sets, start time or duration removes the workout's AI analysis, and the preview says so.
update_workout_plan- Changes a plan's name, expected duration, default rest, or its exercises, sets, rest and supersets.
update_exercise_note- Replaces the text of the note on an exercise.
Delete: 3 tools, preview first
A delete removes the record from every device on its next sync and can't be undone.
delete_workouts- Deletes up to 20 logged workouts, such as a session logged twice.
delete_workout_plans- Deletes up to 10 workout plans. Workouts you logged from them are kept. Schedule days that named a deleted plan stay, with no plan.
delete_exercise_note- Deletes the note on an exercise.
How changes and deletes are confirmed
Every change and delete takes two calls, so nothing changes until you agree to it.
- The first call writes nothing. It returns a preview of every change and a confirmation token.
- The assistant shows you the preview and asks you to confirm.
- Only after you agree does it call again, with the same details and the token.
The token is tied to your account, the tool, the exact details and the record's last edit. It can't be reused or applied to a different change. If the record changed on your phone between the two calls, the change is refused instead of overwriting yours. The token can't tell whether a person said yes, so read the preview before you confirm.
How changes reach the app
- Whatever an assistant adds, changes or deletes reaches the Gymus app on its next sync.
- If you edit the same workout or plan on your phone and in a chat, the later edit wins.
- A delete always wins: an edit made on the phone after it is dropped.
- Your schedule and training profile can be read but changed only in the app. Weigh-ins can be logged but corrected or deleted only in the app. Custom exercises are created only in the app.
What Gymus keeps
- The server receives the details of each tool call, not your conversation, and doesn't log those details.
- Its logs keep the tool, the record ID and your user ID for each change it applies, and the error message of any call it refuses.
- What the assistant receives is processed by its provider, such as OpenAI or Anthropic, under that provider's own privacy policy. The Gymus privacy policy covers what Gymus shares with an assistant you connect, and the terms of use treat what an assistant does on your instruction as done by you.
How to revoke access
Disconnect Gymus in the assistant, and it can't reach your account until you connect it again. Your workouts stay in Gymus.
- ChatGPT: open Plugins, tap Gymus, then the settings button at the top. In the ⋮ menu, choose Disconnect account, or Uninstall to remove the plugin as well.
- Claude: open Settings → Connectors, choose Gymus and disconnect or remove it.
- Claude Code: run
claude mcp remove gymus.
Good to know:
- Gymus doesn't keep a list of connected assistants, so there is no disconnect button in the Gymus app. Disconnect in each assistant you connected.
- Removing Gymus from the third-party connections in your Google Account doesn't disconnect an assistant. Google is used only to sign in. The assistant's access comes from Gymus's own tokens.
- Tokens run out on their own: an access token after 1 hour, and a refresh token 30 days after it was issued. An assistant that keeps using Gymus gets new ones, so disconnecting is what ends its access.
- If you think an assistant you didn't connect has access to your account, contact support.
