TrainHeroic
TrainHeroic MCP Server
TrainHeroic MCP server — connect TrainHeroic to Claude via the Model Context Protocol.
Give Claude (and other AI agents) direct access to your TrainHeroic workout data — history, exercise stats, personal records, and personal calendar — through the Model Context Protocol.
Built from the TrainHeroic mobile API (iOS app v8.25.0, endpoints captured via mitmproxy).
What you can do
Ask Claude things like:
"What workouts did I do this week?"
"What's my working max for back squat and how has it changed?"
"Show me my bench press PRs by rep count."
"Log today's session — I did 4×5 back squat at 225 lbs, RPE 8."
"Create a personal session for tomorrow and add deadlifts and Romanian deadlifts."
"How did I feel after Monday's workout? What was my energy and stress survey?"
"Who's on the leaderboard for Tuesday's workout?"
Related MCP server: paceforge-garmin-mcp
Quick Start
Prerequisites: Python 3.12+ and uv
# 1. Clone and install
git clone https://github.com/cmagorian/trainheroicMcp
cd trainheroicMcp
make install
# 2. Add your credentials
cp .env.example .env
# Edit .env — see "Credentials" section below
# 3. Register with your AI client
make setup-claude # Claude Code
make setup-openclaw # OpenClaw
# See below for Claude Desktop and CursorRestart your AI client and ask: "What did I train this week?"
Credentials
Copy .env.example to .env and choose one of two methods:
Option A — Email + password (recommended)
TRAINHEROIC_EMAIL=you@example.com
TRAINHEROIC_PASSWORD=yourpasswordThe server logs in on first start and caches the session token to ~/.config/trainheroic/session.json. Re-login is automatic when the token expires.
Option B — Session token
If you'd rather not store your password:
Log in at trainheroic.com
Open DevTools (
F12) → Network tabClick any request to
api.trainheroic.comUnder Request Headers, copy the
session-tokenvalue
TRAINHEROIC_SESSION_TOKEN=<your-session-token>Verify your credentials before registering:
make check-env # confirms .env is present and populated
make run # starts the server — look for "Ready — logged in as ..." on stderrRegistering with your AI client
Claude Code
make setup-claudeThis registers the server in .claude/settings.json for this project. Credentials are loaded from .env automatically.
Run /mcp in Claude Code (or restart) to pick up the new server.
Claude Desktop
Open the config file for your OS:
OS | Path |
macOS |
|
Windows |
|
Linux |
|
Add the trainheroic entry — replace the path and credentials:
{
"mcpServers": {
"trainheroic": {
"command": "uv",
"args": [
"run",
"--directory", "/absolute/path/to/trainheroicMcp",
"python", "-m", "trainheroic_mcp.server"
],
"env": {
"TRAINHEROIC_EMAIL": "you@example.com",
"TRAINHEROIC_PASSWORD": "yourpassword"
}
}
}
}Restart Claude Desktop after saving.
Cursor
Open Cursor Settings → MCP → Add new MCP server, or edit ~/.cursor/mcp.json directly:
{
"mcpServers": {
"trainheroic": {
"command": "uv",
"args": [
"run",
"--directory", "/absolute/path/to/trainheroicMcp",
"python", "-m", "trainheroic_mcp.server"
],
"env": {
"TRAINHEROIC_EMAIL": "you@example.com",
"TRAINHEROIC_PASSWORD": "yourpassword"
}
}
}
}Restart Cursor after saving.
OpenClaw
make setup-openclawThis registers the server in ~/.openclaw/openclaw.json. Restart OpenClaw to pick it up.
Example prompts
Checking history
What workouts did I complete last week?
Show me everything I trained in May.
Did I train on Monday?Exercise stats and PRs
What's my current working max for back squat?
Show me my bench press PRs broken down by rep count.
What were my last 3 performances on Romanian deadlifts?Logging a session
Create a personal session for today and add back squat, bench press, and cable rows.
Log my workout — I completed all sets. RPE was 7, rating 8 out of 10.Surveys and recovery
What were my energy and stress scores after Tuesday's workout?
Submit my readiness survey: sleep was good, mood was great, energy was ok.Social
Who's on the leaderboard for this week's main lift?
What comments are on today's workout?Available tools
Core data
Tool | What it does | Key params |
| Name, ID, coach status | — |
| Teams, program IDs, coaches | — |
| Workouts in a date range (flat summary by default) |
|
| Full sets + logged weights for one session |
|
| Last performance, PR, working max |
|
| All PRs by rep count |
|
| Current working max |
|
Tip:
get_workout_historyreturns compact summaries (date, title, rating, RPE, notes) by default. Passinclude_sets=Truefor set-level data on a 1–3 day window, or callget_workout_detailsfor a single session.
Exercise library
Tool | What it does | Key params |
| Full library; filter by name |
|
| Full circuit library | — |
| Recently used exercises | — |
| Recently used circuits | — |
Personal calendar
Tool | What it does | Key params |
| Create a new session |
|
| Add exercises in order |
|
| Save a completed workout |
|
| Delete a session |
|
Surveys & messaging
Tool | What it does | Key params |
| Sleep/mood/energy/soreness/stress data |
|
| Answer a survey question |
|
| Comments on a workout |
|
| Full leaderboard for a workout |
|
Survey reference:
Sleep | Mood | Energy | Soreness | Stress | |
| 8 | 9 | 10 | 11 | 12 |
| 1 | 2 | 3 | 4 | 5 |
Meaning | Awful | Poor | Ok | Good | Excellent |
Deploying online (access from any machine)
Host the server on Railway so any device running Claude Code, Claude Desktop, or OpenClaw can connect to it over HTTPS — no local Python install needed on the client.
Step 1 — Generate an auth token
make generate-token
# prints: MCP_AUTH_TOKEN=e5b7a8e3...Copy the full line — you'll need it in Steps 2 and 3.
Step 2 — Deploy to Railway
Push this repo to GitHub
Go to railway.app → New Project → Deploy from GitHub repo
Select the repository — Railway auto-detects the
DockerfileIn Variables, add:
Variable | Value |
|
|
| your email |
| your password |
| the token from Step 1 |
Click Deploy. Railway assigns a URL like
https://trainheroicmcp-production.up.railway.app
Check the deploy logs for:
INFO [trainheroic-mcp] Ready — logged in as Your Name (team: Your Team)
INFO [trainheroic-mcp] HTTP transport — listening on 0.0.0.0:8000/mcpStep 3 — Connect from any machine
Replace YOUR_URL with your Railway URL and YOUR_TOKEN with the token from Step 1.
Claude Code:
claude mcp add \
--transport http \
--header "Authorization: Bearer YOUR_TOKEN" \
trainheroic \
https://YOUR_URL/mcpClaude Desktop / Cursor (claude_desktop_config.json or ~/.cursor/mcp.json):
{
"mcpServers": {
"trainheroic": {
"type": "http",
"url": "https://YOUR_URL/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}OpenClaw:
openclaw mcp set trainheroic \
'{"type":"http","url":"https://YOUR_URL/mcp","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'Test the connection:
curl -s \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
https://YOUR_URL/mcp
# Should return an MCP protocol response, not 401Run HTTP transport locally (before deploying):
MCP_AUTH_TOKEN=test-token make run-http
# Server starts on http://localhost:8000/mcpTroubleshooting
Symptom | Likely cause | Fix |
|
|
|
| Expired or invalid token | Delete |
| Wrong team resolved | Pass |
Server starts but Claude can't find it | Not registered or client not restarted | Re-run |
Responses seem incomplete | Date range too wide | Use 1–2 week windows; call |
Known limitations
Feature | Reason unavailable |
Lift goals | Requires Athlete Pro subscription |
Nutrition calendar | Requires Athlete Pro subscription |
Program listing | Coach accounts only |
Data export | Backend returns 504 timeout |
Development
Running tests
No credentials needed — all HTTP is intercepted by pytest-httpx.
make test # quiet summary
make test-v # verbose, one line per test
uv run pytest -k "TestLogin" # single class
uv run pytest tests/test_client.py # single fileProject structure
src/trainheroic_mcp/
├── client.py # TrainHeroicClient — auth, token cache, HTTP helpers
└── server.py # FastMCP server — 19 tool definitions, response projectors
tests/
├── conftest.py # fixtures: cache isolation (autouse), th_client, patched_server
├── helpers.py # shared constants + add_init_responses helper
├── test_client.py # init, login, token cache, HTTP helpers
└── test_tools.py # one test class per toolAdding a new tool
Add the function to
server.pywith@mcp.tool().Add a test class to
tests/test_tools.pyusing thepatched_serverfixture.
# server.py
@mcp.tool()
def get_athlete_pro_status() -> dict:
"""Check whether the user has an active Athlete Pro subscription."""
return _get_client()._get("/v5/athletePro/access")# tests/test_tools.py
class TestGetAthleteProStatus:
def test_calls_correct_endpoint(self, patched_server, httpx_mock):
httpx_mock.add_response(
method="GET",
url=f"{BASE}/v5/athletePro/access",
json={"hasAthleteProAccess": False},
)
result = server.get_athlete_pro_status()
assert result["hasAthleteProAccess"] is FalseAvailable Tools
20 toolsadd_exercises_to_sessionA
Add exercises to a personal workout session in order.
exercise_ids: ordered list of exercise IDs to add (use get_exercise_library to look up IDs). Returns the created workout sets with full exercise details.
Inputs: workout_id (required), exercise_ids (required).
create_personal_sessionA
Create a new personal training session for a given date (YYYY-MM-DD).
Returns {programWorkout: {id, programId, date, workoutId}, savedWorkout: {id}}. Use the returned workoutId with add_exercises_to_session and savedWorkout.id with log_workout.
Inputs: session_date (required).
delete_sessionB
Delete a program workout / personal session by its ID.
Inputs: program_workout_id (required).
get_circuit_libraryB
Get the circuit library for a team.
Each circuit has id, title, instructions, prescription, and exerciseIds.
Inputs: team_id.
get_exercise_detailA
Get the full, un-slimmed per-set data for ONE exercise within a workout.
Use this after a slim get_workout_details call when you need every logged set (all param_N_* values, prescribed vs. actual) for a specific exercise, without pulling the entire session. Reuses the cached workout-details response.
Pass the exercise_id shown in the slim get_workout_details response, plus the same program_id/team_id you used there so the correct team is resolved.
Inputs: exercise_id (required), program_workout_id (required), team_id, program_id.
get_exercise_libraryB
Get the full exercise library for a team.
Optionally filter by name with query (case-insensitive substring match).
Each exercise has id, title, prescription, param1Type, param2Type, videoUrl, hasVideo.
Inputs: query, team_id.
get_exercise_statsB
Get stats for an exercise: last performance, personal record, and working max.
stat_date is YYYY-MM-DD and defaults to today. Response includes isLift, lastPerformance (text, date, notes), personalRecord, and workingMax.
Inputs: exercise_id (required), stat_date.
get_personal_recordsB
Get all personal records for an exercise, broken down by rep count.
Each entry contains reps, weight, scaledWeight, units, and setNumber.
Inputs: exercise_id (required).
get_recent_circuitsA
Get the user's recently used circuits.
Inputs: no named parameters.
get_recent_exercisesA
Get the user's recently used exercises.
Inputs: no named parameters.
get_team_infoA
Get the athlete's team memberships and license info (team IDs, program IDs, coaches).
Inputs: no named parameters.
get_user_profileA
Get the current user's profile (name, ID, coach status, etc.).
Inputs: no named parameters.
get_working_maxB
Get the current working max for a specific exercise.
Response: {value, hasReferenceMaxExercise, referenceMaxExercise}
Inputs: exercise_id (required).
get_workout_detailsA
Get workout details for a specific program workout: exercises, prescribed vs. logged sets, and coaching notes.
Pass the program_workout_id from get_workout_history.
To ensure the correct team is used, also pass program_id (the program_id field from the
get_workout_history item) — the server will resolve the matching team automatically.
Alternatively, pass team_id directly. Falls back to the user's primary team if neither is given.
slim=True (the DEFAULT, and safe for small/local context windows) removes the
duplicated saved_workout_set_exercises array, per-exercise media (tips/video_url),
and the empty per-set param_N_* value slots. Each exercise is left with its title,
abr (prescribed, e.g. "3 x 10 @ 60 lb"), abr_results (actual), and completed
flags. Coaching/description text is kept but truncated to max_text_chars. The raw
response can exceed 200k characters per session, so keep slim on unless you
specifically need the full per-set logged values.
slim=False returns the full response (media fields still stripped). For the full per-set data of a SINGLE exercise without the whole session, use get_exercise_detail(program_workout_id, exercise_id) instead.
Inputs: program_workout_id (required), slim, team_id, cache_bust, +2 more.
get_workout_historyA
Get workout history for a date range.
Dates must be YYYY-MM-DD. If omitted, defaults to the last weeks_back weeks.
Fetches one day at a time to guarantee the full day's data is returned.
By default (include_sets=False) each item is projected to a flat summary: id, workout_id, program_id, date, workout_title, feed_item_id, saved_workout_id, completed, workout_rating, rpe, notes. Use this for scanning history and finding sessions — it's intentionally small.
Set include_sets=True only when you need set-level exercise data AND you are querying a narrow range (1-3 days). For full set data on a single known session, prefer get_workout_details(program_workout_id, program_id) instead.
Set cache_bust=True to force a fresh API fetch for every day in the range, ignoring and overwriting any cached data regardless of TTL.
Inputs: end_date, cache_bust, start_date, weeks_back, +1 more.
get_workout_leaderboardB
Get the leaderboard for a specific program workout.
Returns {workoutId, workoutTitle, date, tests, results, testStats, userResult}.
Inputs: program_workout_id (required).
get_workout_messagesA
Get the messaging stream and all comments for a workout.
Returns {stream: {id, title, lastActivity, ...}, comments: [...]} where each comment has content, authorName, replies, and reactions.
Inputs: program_workout_id (required), team_id.
get_workout_surveysA
Get pre/post workout surveys for one or more saved workout IDs.
Returns a map of savedWorkoutId → survey data with Sleep, Mood, Energy, Soreness, Stress questions.
Inputs: saved_workout_ids (required).
log_workoutB
Save/log a completed workout with results.
saved_workout_id: from create_personal_session or get_workout_details. workout_id: the workout's workoutId. date_string: YYYY-MM-DD date of the session. blocks: list of block/set IDs that were completed. rpe: Rate of Perceived Exertion (1-10). workout_rating: numeric rating as string e.g. "8.0".
Inputs: blocks (required), workout_id (required), date_string (required), saved_workout_id (required), +4 more.
submit_surveyA
Submit a readiness/recovery survey answer for a workout.
Question IDs: 8=Sleep, 9=Mood, 10=Energy, 11=Soreness, 12=Stress Answer IDs: 1=Awful/VeryPoor, 2=Poor, 3=Ok, 4=Good, 5=Excellent
Inputs: answer_id (required), question_id (required), saved_workout_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Most tools target distinct resource+action pairs. A few exercise performance tools (get_exercise_stats, get_personal_records, get_working_max) overlap in information returned, but descriptions clarify their specific scopes. Overall, agents can reliably select the right tool.
Tool names mostly follow a verb_noun pattern with get_ prefix for reads and action verbs for mutations. A minor inconsistency exists between 'session' and 'workout' terminology (create_personal_session vs log_workout), and some nouns are singular vs plural, but the pattern is predictable and consistent in style.
20 tools is on the heavier side but each covers a distinct aspect of the training domain: user/team info, session management, workout logging, surveys, messaging, leaderboards, and exercise data. No tool feels redundant, though the count could be trimmed by merging some exercise stat tools.
Core session lifecycle (create, add exercises, log, delete) is covered, along with history, details, surveys, and leaderboards. Notable gaps include no update/remove exercises from a session, no upcoming workout schedule, and circuits cannot be added to sessions despite having a library. These are working gaps agents may need to work around.
Maintenance
Related MCP Connectors
Read athletes, workouts, scores and movements; change an athlete's name or email in SugarWOD.
Manage clients, workout and meal plans, check-ins, habits.
Agent-first strength-training platform across iOS, Web & MCP: read & write workouts, PRs & plans.
Read your workouts, history, and stats; create and schedule new workouts. Writes are additive only.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables agents to track workouts, body metrics, and training stats for registered users through a JSON-RPC MCP endpoint, with scoped agent permissions and a web dashboard.-
- AlicenseNot gradedqualityDmaintenanceEnables MCP hosts to read Garmin training data and write structured workouts to a calendar, with tools for listing activities, summarizing training, computing athlete zones, building and scheduling workout plans, syncing data, and checking cache status.1MIT
- FlicenseNot gradedqualityBmaintenanceEnables reading a Garmin Connect account, creating structured workouts, and scheduling calendar entries via MCP.-
- AlicenseNot gradedqualityCmaintenanceEnables querying a Tonal fitness account for workout history with per-set weights, muscle readiness, strength scores, and lifetime stats through a remote MCP endpoint.MIT