Trainzilla Coach MCP server

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 (94 tools, 1 resource, 1 prompt)

Read (live data):

• whoami, listclients, getclient_profile
• listclienthabits, gethabitcompliance, recenthabitactivity, master_habits
• listworkoutplans, listdietplans
• listcheckins, listsessions, listsubscriptions, billingsummary

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:

• createhabit, createmasterhabit, assignmaster_habit
• createcheckin (with questions), schedulesession
• createworkoutplan, createdietplan

Still not exposed: deletes, payment execution/refunds, messaging, permission changes — by design.

Resource: tzilla://client/{clientId}/profile — a client's profile as JSON.

Prompt: weeklyclientreview — 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 MCPHTTPPORT / MCPHTTPHOST).
• Smoke: node scripts/smoke-http.mjs

Auth modes

(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.

• stdio: uses TZACCESSTOKEN (+ TZREFRESHTOKEN) from env; auto-refreshes.
• Endpoint selection:
• TZAPIURL 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

Backend: trainer API keys (built in tzilla-be, local — not deployed yet)

owning coach, and stamps lastUsedAt. Only a SHA-256 hash is stored.

• 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

Use from Claude Desktop

Add to claudedesktopconfig.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

Shortened. The full README is on GitHub.