Skip to main content
Glama
Sign In
trainheroic-mcp

trainheroic-mcp

by IBazylchuk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

trainheroic-mcp

An unofficial Model Context Protocol server for TrainHeroic. It lets Claude (or any MCP client) read your training history and plan complete workouts on your personal calendar: exercises from the TrainHeroic library (each with its video and technique notes), sets, reps, per-set weights, supersets, session notes and block instructions.

Unofficial. TrainHeroic has no public API. This server talks to the same endpoints the TrainHeroic apps use, so it can break whenever they change, and automated access may not be allowed by TrainHeroic's terms. Use it for your own account, at your own risk.

What you can ask

  • "Build next week's two sessions: trap bar deadlift 3×8 at 30/35/40 kg, split squats, incline DB press, lat pulldown, calves."

  • "Show Tuesday's workout with links to the exercise videos."

  • "Bump all deadlift sets in Thursday's session by 2.5 kg."

  • "Find a landmine press variation that has a video."

  • "Copy this week's two sessions to the next three weeks, +2.5 kg on the main lifts."

Related MCP server: mcp-fitbod

Tools

Area

Tool

What it does

Account

get_profile

Athlete id, name, coach teams

History

get_workout_history

Sessions in a date range (past or planned)

get_workout

One session: blocks, exercises, prescription, results, video links

get_set_exercise

Per-set values for one exercise

Library

search_exercises, get_exercise

Find exercises (all words must match), with video links

search_circuits, get_recent_exercises, get_recent_circuits

Performance

get_exercise_stats, get_personal_records, get_working_max

Feedback

get_workout_surveys, submit_survey, get_workout_comments, get_workout_leaderboard, save_workout_feedback

Planning

create_workout

Whole session in one call, supersets included; rolls back if any step fails

create_session, add_exercises, add_to_block, set_prescription

Build or edit step by step; add_to_block turns a block into a superset

update_session, update_block

Titles, notes, block instructions

remove_exercise, remove_block, delete_session

Remove an exercise (an emptied block goes too), a block or a session

copy_workout, move_workout

Repeat a session's plan on another date; reschedule a session

Weights are always passed in kilograms; the server converts to the pounds the API stores and the app shows them in your preferred units. Targets can be one value for every set or a list with a value per set (weight_kg: [30, 35, 40, 40]). Only targets the exercise actually tracks are accepted, so a typo like weight on a bodyweight drill fails loudly instead of being dropped.

Supersets

TrainHeroic has no separate superset object: a block that holds several exercises is a superset. In create_workout, give exercises the same superset label to put them in one block (the label becomes the block title unless block_title is set):

[
  {"exercise_id": 68077, "reps": 8, "weight_kg": [30, 35, 40], "superset": "A"},
  {"exercise_id": 1971, "reps": 10, "weight_kg": 30, "superset": "A",
   "block_instruction": "Alternate, rest 90 s after each pair"}
]

Setup

Requires Python 3.12+ and uv.

git clone https://github.com/IBazylchuk/trainheroic-mcp
cd trainheroic-mcp
uv sync

Credentials

Either of:

Variable

Notes

TRAINHEROIC_EMAIL + TRAINHEROIC_PASSWORD

Logs in and caches the session token; re-logs in when it expires

TRAINHEROIC_SESSION_TOKEN

The session-token header from a logged-in TrainHeroic web session

Optional: TRAINHEROIC_CONFIG_DIR (default ~/.config/trainheroic-mcp) holds the cached token, the exercise library cache and the ids it learned about your calendar. TRAINHEROIC_LOG_LEVEL=DEBUG logs every API call to stderr.

Claude Code

claude mcp add trainheroic \
  -e TRAINHEROIC_EMAIL=you@example.com -e TRAINHEROIC_PASSWORD=... \
  -- uv run --directory /path/to/trainheroic-mcp trainheroic-mcp

To keep the password out of config files, start the server through a secrets manager, e.g. a wrapper script with the 1Password CLI:

#!/bin/sh
# op.env contains: TRAINHEROIC_EMAIL=op://Private/TrainHeroic/username
#                  TRAINHEROIC_PASSWORD=op://Private/TrainHeroic/password
exec op run --no-masking --env-file "$HOME/.config/trainheroic-mcp/op.env" -- \
  uv run --directory /path/to/trainheroic-mcp trainheroic-mcp

and register the script instead: claude mcp add trainheroic -- /path/to/script.sh.

Claude Desktop / other clients

{
  "mcpServers": {
    "trainheroic": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/trainheroic-mcp", "trainheroic-mcp"],
      "env": { "TRAINHEROIC_EMAIL": "you@example.com", "TRAINHEROIC_PASSWORD": "..." }
    }
  }
}

Limitations

  • Only personal calendar sessions can be created or edited. Coach programs are read-only, and once a coach license expires TrainHeroic hides those sessions from the API entirely (use the app's data export for that history).

  • TrainHeroic has no reschedule call for personal calendars, so move_workout re-creates the session on the new date and deletes the old one (ids change). Sessions with logged results are never moved, only copied.

  • For personal sessions the TrainHeroic app writes the reps and weights you type while logging back into the plan; the original targets are not kept anywhere. Copying a logged personal session therefore repeats what you entered, and copy_workout says so in its result.

  • Logging set results and marking a session complete happen in the TrainHeroic app; save_workout_feedback only stores notes, RPE and rating.

  • Reps must be whole numbers. Put "per side", tempo or rest cues in the exercise or block instruction.

Development

uv sync --all-groups
uv run pytest          # no network, all HTTP is mocked
uv run ruff check . && uv run ruff format --check .

Code map:

  • api.py — HTTP client: auth and token cache, errors, team resolution, library cache.

  • workouts.py — pure functions that parse workout payloads and build prescriptions.

  • units.py — parameter types and kg/lb conversion.

  • server.py — MCP tools.

License

MIT

Available Tools

29 tools
add_exercisesB

Append library exercises to a personal session, each in its own block.

Returns the ids needed by set_prescription and update_block.

Inputs: workout_id (required), exercise_ids (required). Returns: result

add_to_blockB

Append library exercises to an existing block, turning it into a superset.

Set their targets afterwards with set_prescription.

Inputs: block_id (required), exercise_ids (required), program_workout_id (required), team_id. Returns: result

copy_workoutB

Copy a session's plan to another date on your personal calendar.

Blocks, supersets, sets/reps/weights, cues and notes are copied; logged results are not. Works for coach sessions too, as long as they are visible. For personal sessions the app writes values typed while logging back into the plan, so a logged personal session copies those values (the result says so).

Inputs: to_date (required), program_workout_id (required), title, team_id.

create_sessionC

Create an empty personal session on a date (YYYY-MM-DD).

Inputs: date (required), title, instruction.

create_workoutA

Create a complete personal session in one call.

Exercises go into blocks in the given order, each with its prescription and cue. Exercises sharing a superset label are placed together in one block. If any step fails the half-built session is deleted.

Inputs: date (required), title (required), exercises (required), instruction.

delete_sessionC

Delete a session from the calendar.

Inputs: program_workout_id (required).

get_exerciseB

Full library entry for one exercise: technique notes, video, tracked params.

Inputs: exercise_id (required).

get_exercise_statsC

Last performance, personal record and working max for an exercise.

Inputs: exercise_id (required), on_date.

get_personal_recordsC

Personal records for an exercise by rep count.

Inputs: exercise_id (required).

get_profileC

The athlete's id, name and the coach teams they belong to.

Inputs: no named parameters.

get_recent_circuitsC

Circuits the athlete used recently.

Inputs: no named parameters.

get_recent_exercisesC

Exercises the athlete used recently.

Inputs: no named parameters.

get_set_exerciseC

Per-set prescribed and logged values for one exercise of a session.

Inputs: program_workout_id (required), workout_set_exercise_id (required), team_id.

get_working_maxD

Current working max for an exercise.

Inputs: exercise_id (required).

get_workoutC

One session: title, notes, blocks, exercises with prescription, results and video.

team_id is optional; the right team is found automatically.

Inputs: program_workout_id (required), team_id.

get_workout_commentsC

Comment thread of a session (coach and athlete messages).

Inputs: program_workout_id (required), team_id.

get_workout_historyA

Sessions scheduled between two dates (YYYY-MM-DD, inclusive), oldest first.

Defaults to the last days_back days. Future dates work too, which is how to review a planned block. Each row has the ids needed by the other tools.

Inputs: end_date, days_back, start_date. Returns: result

get_workout_leaderboardC

Team leaderboard for a session.

Inputs: program_workout_id (required).

get_workout_surveysB

Readiness answers (sleep, mood, energy, stress, soreness) for saved workouts.

Scores run from 1 (worst) to 5 (best).

Inputs: saved_workout_ids (required).

move_workoutA

Reschedule a personal session that has no logged results yet.

TrainHeroic offers no reschedule call for personal calendars, so the session is copied to to_date and the original deleted: its ids change.

Inputs: to_date (required), program_workout_id (required), team_id.

remove_blockC

Remove a whole block (all its exercises) from a session.

Inputs: block_id (required).

remove_exerciseB

Remove one exercise from a session; a block left empty is removed too.

Inputs: program_workout_id (required), workout_set_exercise_id (required), team_id.

save_workout_feedbackB

Save the athlete's session notes, RPE (1-10) and rating.

This does not log per-set results or mark the session completed; that is done in the TrainHeroic app.

Inputs: program_workout_id (required), rpe, notes, rating, +1 more.

search_circuitsB

Find circuits (predefined exercise groups) in the library by name.

Inputs: limit, query. Returns: result

search_exercisesA

Find exercises in the TrainHeroic library by name (all words must match).

Returns id, title, what the exercise tracks (e.g. "Reps @ Weight (lb)") and the video link. The library is cached for 24h; pass refresh=True to reload.

Inputs: query (required), limit, refresh, with_video_only. Returns: result

set_prescriptionA

Set sets and per-set targets for one exercise of a session you own.

Each target is one value for all sets or a list with one value per set, e.g. sets=4, reps=8, weight_kg=[30, 35, 40, 40]. Targets and the set count you leave out keep their planned values, so weight_kg=42.5 alone only changes weights. Reps are whole numbers; write "per side" or tempo cues in instruction. Only targets the exercise tracks are accepted (see tracks in get_workout).

Inputs: program_workout_id (required), workout_set_exercise_id (required), rpe, reps, +8 more.

submit_surveyB

Answer one readiness question for a saved workout; score 1 (worst) to 5 (best).

Inputs: score (required), question (required), saved_workout_id (required).

update_blockC

Rename a block and/or set its instruction (e.g. warm-up circuit, rest times).

Inputs: block_id (required), program_workout_id (required), title, team_id, +1 more.

update_sessionC

Rename a session and/or set its notes. Omitted fields stay unchanged.

Inputs: workout_id (required), title, instruction.

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    C2.8/5.0

    Scored across 29 tools

    Disambiguation4/5

    Most tools target distinct resource/action pairs, and descriptions clarify granular session editing such as create_session vs create_workout, add_exercises vs add_to_block, and copy_workout vs move_workout. Some exercise-stat tools (get_exercise_stats, get_personal_records, get_working_max) and session variants still require careful selection, so the set is not perfectly unambiguous.

    Naming Consistency5/5

    Almost all tools use predictable snake_case verb_noun names, e.g. create_session, update_block, get_workout_comments. add_to_block is a minor prepositional variant but remains readable and consistent with the overall convention.

    Tool Count2/5

    At 29 tools, the set is heavy and exceeds the typical well-scoped range; several granular session-editing and exercise-stat retrieval tools feel like they could be consolidated. The domain is broad enough to justify many operations, but the count is still above what the surface needs.

    Completeness4/5

    The core lifecycle is covered: sessions, blocks, exercises, prescriptions, copying/moving, library search, history, stats, surveys, comments, and feedback. Minor gaps remain, such as no posting comments and no per-set result logging, though the latter is explicitly app-only.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • mcp-fitbod

      Muno459
      A
      license
      Not graded
      quality
      C
      maintenance
      Enables reading Fitbod training history, generating workouts via Fitbod's engine, configuring workout programs, and tracking body composition over time.
      3
      MIT

    • GeniusFitness MCP

      PulsarInteractive
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to access and manage fitness programs, exercise catalog, workout resources, activity metrics, journaled plan edits, and change tracking through authenticated tools.
      52 npm
      MIT

    • Phorme Training

      nicksgoat
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to find coach-built training programs, coaching brains, races, gyms, classes and sports clinics, preview and build workouts with exercise demos, swap exercises, and plan around a sport or race. With OAuth it can also save workouts and programs, send coach notes to members, and read a member's logged history, planned sessions and lift progress.
      MIT