GeniusFitness CLI & MCP

Manage your training plans, exercises and progress with your own AI tools. GeniusFitness keeps your programs and permissions in one place; your agent uses its own model and credentials.

Install and connect

Requires Node.js 22.13 or newer.

npm install --global @pulsarinteractive/geniusfitness@beta
geniusfitness auth login
geniusfitness whoami --json
geniusfitness programs list --json

Login opens your browser. Sign in to GeniusFitness, select programs and permissions, then approve. There is no token to copy into your terminal.

Related MCP server: OpenGym Coach

What you can do

Choose from the exercise catalogue before creating a custom exercise. Private health measurements require separate permission. Managing another athlete’s shared program also requires a Coach subscription and that athlete’s access grant.

Connect your agent

Authenticate once with the CLI, then configure your MCP client to run:

geniusfitness mcp --context default

Setup examples · Training workflow · Permissions and limits · Agent skills

Documentation

• CLI reference

• Authentication and account safety

• Contributing

• Security reports

MIT © Pulsar Interactive. This repository contains the public agent client and skills; the GeniusFitness application and service implementation are separate.

ChatGPT

Connect the hosted service with OAuth: setup and examples. Your computer does not need to run the CLI. Account permissions and quotas still apply. Official directory publication is a separate review.

Reuse a coach catalogue workout

Use fitness_workout_copy_preview (CLI: workouts copy-preview) with the coach-owned source program/workout and the student's destination program. Prepare workout.copy with the returned source fingerprint and target epoch. The student owns an independent copy, including exercise definitions.

For a later update, preview the saved copyOrigin with targetTraining, then confirm workout.sync using both fingerprints and the target revision. The student's prescription customizations are replaced; schedules, completed results, progress and health measurements are preserved. No automatic sync. Current Coach entitlement, the student's planning grant, source reads and destination writes are rechecked by the server.

Recorded Push bonus results

geniusfitness sessions push-results --scope project:ID --sessionId UUID --json reads one selected training session. MCP provides fitness_push_results; pass athleteId for an authorized student. Results distinguish performed values, usual values and the offered bonus, including units, missing observations and corrections. On supporting servers, add --includeRewardDetails true (MCP includeRewardDetails: true) for the exact settled awardedXp after caps. Missing/null amounts stay unknown, including older awarded outcomes. This is bonus XP for the outcome, not total session XP or physical progression. This read requires metrics:read and current program access. It cannot execute a bonus, award XP or update a prescription. It is available only on servers that implement the Push result endpoint; an unavailable route is not an empty result.

Later workout adjustments

Use fitness_push_adjustments or geniusfitness sessions push-adjustments --scope project:ID --athleteId USER --sessionId UUID --outcomeId ID --json with a current outcome from fitness_push_results. Each explicit call reads one retained occurrence and up to 16 decisions. Empty pages may have a nextCursor; continue with --cursor when needed. Saved/withdrawn values and dates explain a historical decision, not whether it is currently applied. Current program grants and named-coach rights are enforced on every page. This read grants no write or private health access. Server rollout and package publication are separate.

The optional goalProfileKey on adjustment-history entries is an opaque, athlete-bound reference to the profile version used for that decision. It is not the current goal, a progress score, or permission to read private profile answers. A missing key or unavailable version must stay unknown; never join by goal label or date.