Trainzilla Coach MCP server
Commit Nov 9, 2026Lets an AI client manage fitness clients, workout plans, nutrition, habits, and billing via the Trainzilla GraphQL API.
Also known as Trainzilla/tzilla-mcp, tzilla-mcp
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Nov 9, 2026
- License
- —
What is Trainzilla Coach MCP?
Trainzilla Coach lets an AI client manage fitness clients, workout plans, nutrition, habits, and billing via the Trainzilla GraphQL API. It exposes 4 tools, such as calc_tdee, calc_macros, calc_1rm.
Summary generated from the project's README
About Trainzilla Coach MCP server
Fitness professionals managing client rosters can use this local MCP server to handle workout plans, nutrition, habits, and billing directly through an AI client like Claude Desktop or Cursor. By wrapping the Trainzilla GraphQL API, the server allows an AI to act as a virtual coach that can read live client data, such as habit compliance and billing summaries, or perform offline calculations for TDEE, macros, and one-rep-max suggestions.
To prevent accidental changes, all write operations like creating diet plans or scheduling sessions are confirm-gated, meaning the AI provides a preview before any data is modified. The server runs locally on your machine and requires a coach access token and refresh token from the Trainzilla web app to function. It also supports bulk client invitations and group assignments, making it a central hub for managing large coaching businesses or gym-wide workflows through a conversational interface.
What you can do with it
- 1Calculate client nutritional needsAsk the AI to determine a client's recommended calorie intake and macro splits using offline math tools.
- 2Perform weekly client auditsUse a specialized prompt to generate a read-only summary of a client's habits, compliance, and recent sessions.
- 3Migrate client data from other platformsHand an export or spreadsheet to the AI to bulk invite clients and map their information into the system.
Written from the project's README. Every use case is checked against a quote from it.
How to install Trainzilla Coach MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Trainzilla Coach MCP in Claude Code
$ claude mcp add --transport http tzilla-mcp https://api.tzilla.live/mcpInstall Trainzilla Coach MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"tzilla-mcp": {
"url": "https://api.tzilla.live/mcp"
}
}
}Install Trainzilla Coach MCP in VS Code
.vscode/mcp.json
{
"servers": {
"tzilla-mcp": {
"type": "http",
"url": "https://api.tzilla.live/mcp"
}
}
}Install Trainzilla Coach MCP in VS Code CLI
$ code --add-mcp '{"name":"tzilla-mcp","type":"http","url":"https://api.tzilla.live/mcp"}'Install Trainzilla Coach MCP in Codex
$ codex mcp add tzilla-mcp --url https://api.tzilla.live/mcpInstall Trainzilla Coach MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.tzilla-mcp] url = "https://api.tzilla.live/mcp"
Install Trainzilla Coach MCP in Gemini CLI
$ gemini mcp add -s user --transport http tzilla-mcp https://api.tzilla.live/mcpInstall Trainzilla Coach MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"tzilla-mcp": {
"url": "https://api.tzilla.live/mcp",
"type": "http"
}
}
}Trainzilla Coach MCP tools 4
Detected from the READMEcalc_tdeecalc_macroscalc_1rmcreate_checkin
| calc_tdee | — | |
| calc_macros | — | |
| calc_1rm | — | |
| create_checkin | — |
Configuration
TZ_ACCESS_TOKENTZ_API_URLTZ_REFRESH_TOKEN
| Name | Description | |
|---|---|---|
| TZ_ACCESS_TOKEN | — | |
| TZ_API_URL | — | |
| TZ_REFRESH_TOKEN | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachabletrainzilla/tzilla-mcp is public and reachablegithub.com/trainzilla/tzilla-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-09github.com/trainzilla/tzilla-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model4 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubtzilla-mcp (MVP, local only)
A local MCP server that lets an MCP client
(Claude Desktop, Claude Code, Cursor, …) act as a Trainzilla coach. It wraps
the existing GraphQL API at api.tzilla.live — no direct DB access — so all
auth and business rules stay enforced by the backend.
Status: Local MVP — read tools, offline calculators, and confirm-gated write tools, plus a resource + a prompt. Not deployed anywhere. Runs entirely on your machine against your own coach login.
What it can do today (360 tools, 1 resource, 1 prompt)
Read (live data):
whoami,list_clients,get_client_profilelist_client_habits,get_habit_compliance,recent_habit_activity,master_habitslist_workout_plans,list_diet_planslist_checkins,list_sessions,list_subscriptions,billing_summary
Calculators (offline, no network):
calc_tdee— BMR / TDEE / recommended caloriescalc_macros— macro split by strategy (Standard 40/30/30, Pro g/kg, Keto)calc_1rm— 1-rep-max (Epley) + %1RM weight suggestions
Write (confirm-gated): every write tool returns a preview unless called
with confirm: true, so nothing changes by accident:
create_habit,create_master_habit,assign_master_habitcreate_checkin(with questions),schedule_sessioncreate_workout_plan,create_diet_plan
Switching from another platform (Nov 2026): bulk_invite_clients (up to 200 clients with name, phone and a private note that lands in the coach's client notes when they connect), the switch_to_trainzilla prompt, and the format-agnostic skill in skills/switch-to-trainzilla/ (a coach hands Claude any export, PDFs or a spreadsheet; Claude maps it, previews, then sends). No vendor presets: nothing here assumes a competitor's export layout.
Coverage added Oct 2026 (src/tools/*, each tool backed by one GraphQL operation and checked
against the backend schema with scripts/validate-docs.mjs):
- Client tracking — diet/workout logs, daily metrics, personal bests, exercise history, progress, health reports, intake forms, no-app (managed) clients + private portal links, contact details; coach-side logging.
- AI coaching — review queue (approve/reject/requeue), trigger/offer, engagement, per-client preferences, AI-plans and self-cancel switches.
- Check-ins & inbox — respond, logs, recurring schedules, clear overdue; notifications; chat room list.
- Business — plans (create/prices/listing/active/session rules/delete), pause/cancel membership, desk payments, direct-pay claim confirm/reject, payments, invoices + settings, share links, Coach Pro pricing/checkout link, referral program, gym seat billing.
- Community, gym, workflows, catalog, profile — community posts/comments, gym kiosks/face/check-ins/standing bookings/imports/staff/domain, workflow edit/delete + gym-wide workflows, PDF plan import, food/recipe/exercise catalog, branding/custom domain/global payout/localization, Google Calendar status, video calls.
- Client groups (Coach Pro / gym), Nov 2026 —
list_client_groups,get_client_group,list_groups_for_client, create/update/delete group,add_group_members/remove_group_members,get_group_overview,list_group_assignments, and the fan-outsassign_workout_to_groups,assign_diet_to_groups,assign_habit_to_groups,message_groups,schedule_checkin_for_groups,book_session_for_groups,undo_group_assignment. The fan-outs preview server-side withoutconfirm(who would get it, who is skipped and why) and are idempotent for 10 minutes.scripts/mcp-groups-e2e.mjsdrives them against a local backend (TZ_API_URL=http://127.0.0.1:4100/graphql).
Validate documents against the backend schema after changing a tool:
npm run build
SCHEMA=/path/to/tzilla-be/schema.graphql GRAPHQL_PKG=/path/to/node_modules/graphql node scripts/validate-docs.mjs
Also included: upload_file (local path on stdio, or base64) → S3 key for the tools that take one (health reports,
PDF plan import, member photo, receipts, community media, branding images); API-key create/list/revoke
(secret shown once); Stripe/Razorpay connect (secrets masked in previews); start_google_calendar_connect
(returns the sign-in URL for the coach to open).
Chat: get_client_chat_messages reads a client's DM history (needs the clientChatMessages backend query, tzilla-be#493).
Not available: taking or refunding a payment — the backend has no coach-facing refund operation, and client checkout is completed by the client's own payment.
Resource: tzilla://client/{clientId}/profile — a client's profile as JSON.
Prompt: weekly_client_review — pulls profile/habits/compliance/sessions and
writes a read-only weekly review.
Setup
npm install
npm run build
Create .env (see .env.example) with a coach's tokens. Easiest source — log in
to the coach web app, then in the browser console:
localStorage.getItem("token") // -> TZ_ACCESS_TOKEN
localStorage.getItem("refreshToken") // -> TZ_REFRESH_TOKEN
The server auto-refreshes the access token via refreshAccessToken when it expires.
Run
Local (stdio) — for Claude Desktop etc.:
- Dev:
npm run dev - Built:
npm start - Smoke:
node scripts/smoke.mjs
Remote (Streamable HTTP) — localhost only, multi-coach:
- Dev:
npm run http· Built:npm run start:http - Listens on
http://127.0.0.1:8787/mcp(setMCP_HTTP_PORT/MCP_HTTP_HOST). - Smoke:
node scripts/smoke-http.mjs
Auth modes
- stdio: uses
TZ_ACCESS_TOKEN(+TZ_REFRESH_TOKEN) from env; auto-refreshes. - Endpoint selection:
TZ_API_URLwins when set.- Otherwise
TZ_ENVIRONMENT=staginguseshttps://qa-be2.tzilla.live/graphql. - All other cases default to
https://api.tzilla.live/graphql.
- HTTP: pass-through — each request must send the coach's API key
(
Authorization: Bearer tz_...orx-api-key). The server never stores tokens; it forwards the caller's key to the GraphQL API, so the backend enforces scope (multi-coach safe). API keys are minted by the backend feature below.
Backend: trainer API keys (built in tzilla-be, local — not deployed yet)
createApiKey(name)→ returns the plaintexttz_…key once + infoapiKeys(list, no secret) ·revokeApiKey(id)- Auth middleware accepts
tz_keys (headerx-api-keyorBearer), resolves the owning coach, and stampslastUsedAt. Only a SHA-256 hash is stored.
Use from Claude Desktop
Add to claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"tzilla-coach": {
"command": "node",
"args": ["C:/New folder/tzilla-mcp/dist/index.js"],
"env": {
"TZ_API_URL": "https://api.tzilla.live/graphql",
"TZ_ACCESS_TOKEN": "<paste>",
"TZ_REFRESH_TOKEN": "<paste>"
}
}
}
}
Restart Claude Desktop, then try: "Use tzilla-coach: who am I, and list my clients."
Roadmap
- Write tools (habits, check-ins, sessions, plans) — confirm-gated
- Resource (client profile) + prompt (weekly review)
- Wider read coverage (plans, check-ins, sessions, billing)
- Backend trainer API keys / PAT (built in
tzilla-be, local — needs PR + deploy) - Remote Streamable-HTTP transport (localhost, API-key pass-through auth)
- Deploy the backend API-key feature; host the HTTP server (TLS) for real remote use
- Full MCP OAuth 2.1 (replace pass-through) for a public connector
- More resources (plans / check-in history) + prompts (e.g. "draft a plan")
Layout
src/
config.ts # env + tiny .env loader
client.ts # GraphQL client: bearer auth + refresh-on-401 + role header
calc.ts # offline coach math (ported from HealthMath/WorkoutMath)
index.ts # MCP server + tool definitions (stdio)
scripts/
smoke.mjs # spawns the server and lists tools (handshake check)
Trainzilla Coach MCP questions
How do I add Trainzilla Coach MCP to Claude Code?
Run claude mcp add --transport http tzilla-mcp https://api.tzilla.live/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Trainzilla Coach MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Trainzilla Coach MCP provide?
It exposes 4 tools, including calc_tdee, calc_macros, calc_1rm, create_checkin.
Are write operations safe from accidental changes?
Yes, all write tools are confirm-gated and return a preview unless you explicitly call them with the confirm flag set to true.
Can the server perform fitness calculations?
Yes, it includes offline calculators for TDEE, macronutrient splits, and 1-rep-max suggestions without needing a network connection.