coach-mcp

An opinionated AI training coach as an MCP server. It pulls your real data from Garmin Connect and prescribes with authority — science-based load management (ACWR), code-enforced injury gates (the server rejects plans that violate an active injury restriction, no matter what the LLM says), and persistent coaching memory so decisions, rationale, and your adaptation patterns survive between conversations. It will tell you "no" when your enthusiasm exceeds your capacity.

All health data and credentials stay on your machine — see Security & Privacy.

Quickstart

You need Python 3.12+, a free Garmin Connect account, and an MCP client (Claude Code, Claude Desktop, or Cursor).

Option A: uvx (recommended)

No install step — your MCP client runs the server on demand:

uvx garmin-coach-mcp

Jump to Connect your MCP client and use uvx as the command.

Option B: from source

git clone https://github.com/snoozelieb/coach-mcp.git
cd coach-mcp

python -m venv .venv
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

pip install -r requirements.txt
cp .env.example .env   # then edit: GARMIN_EMAIL, GARMIN_PASSWORD
python server.py

Related MCP server: claude-garmin

Connect your MCP client

The server needs two environment variables: GARMIN_EMAIL and GARMIN_PASSWORD. Optional: COACH_DATA_DIR (where your coaching data lives); COACH_TOKEN_DIR, COACH_TRANSPORT and COACH_CODE_MODE are covered under Security & Privacy and Advanced. From a source checkout, a .env file works too.

After one successful login the server runs from the stored Garmin tokens (garmin-coach-login performs that login, MFA included), so a client that cannot expand variables in its config can leave GARMIN_PASSWORD out.

To run the server or the helpers from a terminal, set the two variables in that shell first. PowerShell and bash quote differently:

$env:GARMIN_EMAIL = "you@example.com"
$env:GARMIN_PASSWORD = "your-password"

export GARMIN_EMAIL=you@example.com GARMIN_PASSWORD=your-password

Claude Code

claude mcp add coach-mcp \
  --env GARMIN_EMAIL=you@example.com \
  --env GARMIN_PASSWORD=your_garmin_password \
  -- uvx garmin-coach-mcp

Or in .mcp.json (Claude Code expands ${VAR} from your shell environment, so a committed file holds no secret):

{
  "mcpServers": {
    "coach-mcp": {
      "command": "uvx",
      "args": ["garmin-coach-mcp"],
      "env": {
        "GARMIN_EMAIL": "you@example.com",
        "GARMIN_PASSWORD": "${GARMIN_PASSWORD}",
        "COACH_DATA_DIR": "/path/to/your/coach-data"
      }
    }
  }
}

Running from source instead: claude mcp add coach-mcp -- python /full/path/to/coach-mcp/server.py

Claude Desktop

In claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "coach-mcp": {
      "command": "uvx",
      "args": ["garmin-coach-mcp"],
      "env": {
        "COACH_DATA_DIR": "/path/to/your/coach-data"
      }
    }
  }
}

Claude Desktop reads this file as written (no variable expansion), so keep the Garmin password out of it: run garmin-coach-login once in a terminal with GARMIN_EMAIL and GARMIN_PASSWORD set for that command, and the server logs in from the stored tokens from then on. When they expire the tools say so; run the login again.

Cursor

In .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "coach-mcp": {
      "command": "uvx",
      "args": ["garmin-coach-mcp"],
      "env": {
        "GARMIN_EMAIL": "you@example.com",
        "GARMIN_PASSWORD": "${env:GARMIN_PASSWORD}",
        "COACH_DATA_DIR": "/path/to/your/coach-data"
      }
    }
  }
}

If you installed with pip install garmin-coach-mcp instead of uvx, use "command": "garmin-coach-mcp" with no args in any of the blocks above.

First run

1. Create your profile. Run the interactive wizard (installed copies have the console script; a source checkout can run the script):

   garmin-coach-setup                 # pip / uvx install
   python scripts/setup_wizard.py     # source checkout

   Until a profile exists the server runs in setup mode: plan, program and push writes answer setup_required and name the data directory they looked in.

   It creates your athlete profile, training config, and empty plan/memory files in the data directory. Alternatively, create the two required files by hand and let the coach fill in the rest via conversation:

   echo '{"personal":{"name":null},"injury_history":[],"life_constraints":{}}' > data/athlete.json
   echo '{"events":[],"current_block":{"phase":"base"}}' > data/training_config.json

2. Pull your Garmin baseline. In your MCP client, say:

   "Run refresh_athlete_baseline and set up my training."

   The coach pulls your name, weight, age, HR data, and training capacity from Garmin, then starts the onboarding conversation — goals, constraints, injury history, race calendar.

3. Garmin MFA / expired session. Garmin logins are token-cached. If tools start returning AUTH_REQUIRED, recover with:

   garmin-coach-login                 # pip / uvx install
   python scripts/garmin_login.py     # source checkout

   It does a fresh credential login, prompts for the MFA code if Garmin asks, and saves new tokens. Restart the MCP server afterwards.

How it works

1. Snapshot first — every coaching conversation starts from get_coaching_snapshot(): current time context, 7-day week grid (rest days explicit), fitness metrics, plan adherence, open anomalies, injuries, sleep gate.

2. Load hierarchy before prescribing — overall ACWR (injury gate, 0.8–1.3 sweet spot), then sport-specific ACWR (spike detection), then sport-specific CTL (race readiness).

3. Hard gates are code, not vibes — update_weekly_plan and push_plan_to_garmin reject sessions that violate an active injury's restricted activities, and every non-rest session must carry a purpose or the save is refused. Multi-week programs (training_program) are rejected if their starting capacity contradicts your actual history.

4. Grounded in what you've actually done — prescriptions are anchored to your demonstrated per-sport capacity from recent sessions, not template numbers; a weekly plan that outruns that history comes back with grounding_warnings.

5. Curiosity with memory — planned-vs-actual anomalies (missed session, type mismatch, activity on a rest day) register once with a lifecycle (open → asked → resolved); the coach asks you what happened instead of silently assuming.

6. Everything persists — decisions, approvals, adaptation patterns, and season lifecycle (race debriefs, phase transitions) live in local JSON and carry across sessions.

MCP surface

54 tools — you don't call them directly; the coach uses them during conversation:

Every tool carries MCP annotations (read-only / destructive / idempotent / open-world), enforced by tests.

7 prompts: weekly_planning, morning_brief, injury_assessment, week_review, onboarding, race_program, author_session.

7 resources: coach://athlete/profile, coach://plan/current, coach://config/training, coach://coaching/decisions, coach://context/now, coach://coaching/doctrine (the long-form coaching doctrine), coach://authoring/contract (the generated session contract).

Security & Privacy

Everything stays on your machine:

• Credentials: GARMIN_EMAIL/GARMIN_PASSWORD live in your MCP client config or a local .env. Garmin OAuth tokens are cached in a local token store (.garth/ in a source checkout, a per-user garmin-tokens directory for installed copies; override with COACH_TOKEN_DIR).

• Health data: all coaching data (profile, plans, fitness history, sleep, coaching memory) is local JSON in your data directory. There is no backend, no telemetry, no analytics.

• What leaves your machine: requests to Garmin's own API (your credentials/tokens, sent only to Garmin); whatever your MCP client sends to its LLM as part of the conversation; optional public web-page fetches when the coach researches a race, injury, or exercise. Nothing else: the FastMCP startup banner that would check PyPI for updates is disabled.

• Network exposure: stdio by default, nothing listens. The HTTP transports need COACH_HTTP_TOKEN and validate Host/Origin on every request; research fetches go only to public https addresses, pinned to the address that passed the check.

• Single athlete per data directory by design. For multiple athletes, run separate server instances with separate COACH_DATA_DIRs.

See SECURITY.md for details and how to report issues.

Data directory

Resolution order: COACH_DATA_DIR env var → data/ in a source checkout → a per-user data directory (created on first run for installed packages). The only file shipped with the package is methodology.json (safety rules, race templates, personas); everything personal is created locally and never committed.

Advanced

# HTTP transport instead of stdio: a bearer token is required (clients send
# "Authorization: Bearer <token>"); Host and Origin headers are checked on
# every request. COACH_HTTP_INSECURE=1 waives the token on 127.0.0.1 only.
COACH_HTTP_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
COACH_TRANSPORT=http FASTMCP_PORT=8000 garmin-coach-mcp

# Code Mode (search/execute meta-tools instead of 52 individual tools)
pip install fastmcp[code-mode]
COACH_CODE_MODE=1 garmin-coach-mcp

# Standalone morning audit
python scripts/daily_loop.py          # ingest + audit yesterday + template brief (exit 1 if unverified)

# Tests (1,984 tests; clean checkouts use committed sanitized fixtures)
pip install -r requirements-dev.txt
python -m pytest -q

Architecture

coach/server.py registers tools from the coach/ package (11 tool modules, pure parsers, a typed pydantic storage layer, CTL/ATL/ACWR fitness math, a Garmin client with token-first auth, and a workout builder that pushes structured workouts to your watch). The project went through a five-phase modernization — auth rebuild, schema layer, hard gates, sectioned snapshot, packaging — whose full history and rationale live in docs/UPGRADE_ROADMAP.md. Development conventions are in CLAUDE.md.

Acknowledgements

All Garmin Connect access — login, MFA, token handling, activity and health data, and workout upload — runs on python-garminconnect by Ron Klinkien (@cyberjunky) and its contributors (MIT). coach-mcp wouldn't exist without it.

License

MIT