Trainzilla Coach MCP

tzilla-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_profile
• list_client_habits, get_habit_compliance, recent_habit_activity, master_habits
• list_workout_plans, list_diet_plans
• list_checkins, list_sessions, list_subscriptions, billing_summary

Calculators (offline, no network):

• calc_tdee — BMR / TDEE / recommended calories
• calc_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_habit
• create_checkin (with questions), schedule_session
• create_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-outs assign_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 without confirm (who would get it, who is skipped and why) and are idempotent for 10 minutes. scripts/mcp-groups-e2e.mjs drives 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 (set MCP_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_URL wins when set.
• Otherwise TZ_ENVIRONMENT=staging uses https://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_... or x-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 plaintext tz_… key once + info
• apiKeys (list, no secret) · revokeApiKey(id)
• Auth middleware accepts tz_ keys (header x-api-key or Bearer), resolves the owning coach, and stamps lastUsedAt. 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": " ", "TZ_REFRESH_TOKEN": " " } } } }

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)