coach-mcp

coach-mcp

一款理念鲜明的 AI 训练教练，以 MCP 服务的形式提供。它会从 Garmin Connect 拉取你的真实数据，并权威地开具训练方案——基于科学的负荷管理（ACWR）、由代码强制执行的伤病限制（无论大模型怎么说，服务都会拒绝违反当前伤病限制的计划），以及持久化的教练记忆，让决策、理由和你的适应模式在对话间得以保留。即使你的热情超出了身体承受能力，它也会对你说“不”。

所有健康数据和凭据都保存在你的设备上——请参阅安全与隐私。

快速开始

你需要 Python 3.12+、一个免费的 Garmin Connect 账号，以及一个 MCP 客户端（Claude Code、Claude Desktop 或 Cursor）。

选项 A：uvx（推荐）

无需安装——MCP 客户端会按需运行服务：

uvx garmin-coach-mcp

跳转到连接 MCP 客户端，并将 uvx 用作命令。

选项 B：从源代码运行

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

连接 MCP 客户端

服务需要两个环境变量：GARMIN_EMAIL 和 GARMIN_PASSWORD。可选项：COACH_DATA_DIR（存放教练数据的位置）；COACH_TOKEN_DIR、COACH_TRANSPORT 和 COACH_CODE_MODE 的说明见安全与隐私和高级用法。 从源代码检出目录运行时，也可以使用 .env 文件。

要从终端运行服务或辅助脚本，请先在该 shell 中设置这两个变量。PowerShell 和 bash 的引号用法不同：

$env:GARMIN_EMAIL = "[email protected]"
$env:GARMIN_PASSWORD = "your-password"

export [email protected] GARMIN_PASSWORD=your-password

Claude Code

claude mcp add coach-mcp \
  --env [email protected] \
  --env GARMIN_PASSWORD=your_garmin_password \
  -- uvx garmin-coach-mcp

也可以在 .mcp.json 中配置（Claude Code 会从 shell 环境中展开 ${VAR}，因此提交的文件不会包含机密信息）：

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

如果要从源代码运行：claude mcp add coach-mcp -- python /full/path/to/coach-mcp/server.py

Claude Desktop

在 claude_desktop_config.json 中配置（Settings → Developer → Edit Config）：

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

Cursor

在 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）中配置：

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

如果你使用 pip install garmin-coach-mcp 安装，而非使用 uvx，请在以上任一代码块中使用 "command": "garmin-coach-mcp"，且不带任何参数。

首次运行

1. 创建个人资料。 运行交互式向导（已安装的版本提供控制台脚本；从源代码检出目录运行时也可以运行该脚本）：

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

   在个人资料创建之前，服务会以设置模式运行：计划、训练计划和推送写入会返回 setup_required，并指出它们查找过的数据目录。

   脚本会在数据目录中创建你的运动员个人资料、训练配置，以及空白的计划和记忆文件。你也可以手动创建两个必需文件，然后通过对话让教练补全其他内容：

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

2. 拉取 Garmin 基准数据。 在 MCP 客户端中说：

   “运行 refresh_athlete_baseline 并设置我的训练。”

   教练会从 Garmin 拉取你的姓名、体重、年龄、心率数据和训练能力，然后开始引导对话，了解你的目标、限制、伤病史和比赛日历。

3. Garmin MFA / 会话过期。 Garmin 登录信息会以令牌缓存。如果工具开始返回 AUTH_REQUIRED，请按以下步骤恢复：

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

   这会使用凭据重新登录；如果 Garmin 要求输入 MFA 验证码，则会提示你输入，并保存新的令牌。之后重启 MCP 服务。

工作原理

1. 先获取快照 — 每次指导对话都从 get_coaching_snapshot() 开始：当前时间背景、7 天周计划表（明确标出休息日）、体能指标、计划执行情况、未解决的异常、伤病和睡眠门槛。
2. 开具训练建议前先了解层级 — 总体 ACWR（伤病门槛，0.8–1.3 为理想区间），然后是专项 ACWR（检测训练量激增），最后是专项 CTL（评估比赛准备情况）。
3. 硬性门槛由代码把关，而非凭感觉 — update_weekly_plan 和 push_plan_to_garmin 会拒绝违反有效伤病限制活动的训练；每个非休息训练都必须包含 purpose，否则将拒绝保存。如果多周计划（training_program）的起始能力与实际训练记录不符，也会被拒绝。
4. 以实际完成的训练为依据 — 训练建议以你近期训练所体现的各专项能力为基准，而非模板数值；如果周计划超出历史训练记录所能支持的范围，就会返回 grounding_warnings。
5. 保持好奇，并记住情况 — 计划与实际的异常（漏练、训练类型不符、休息日进行活动）会按生命周期（未解决 → 已询问 → 已解决）登记一次；教练会询问你发生了什么，而不是默默猜测。
6. 所有内容都会持久保存 — 决策、审批、适应模式和赛季生命周期（赛后复盘、阶段转换）都保存在本地 JSON 中，并在不同会话间延续。

MCP 接口

共有 51 个工具 — 你无需直接调用；教练会在对话中使用它们：

类别	工具
指导核心	get_coaching_snapshot（规范化、分节呈现）、get_compliance_report、get_coaching_score
计划	get_weekly_plan、update_weekly_plan、push_plan_to_garmin、training_program（action=get/set；多周计划，以能力为基准并受伤病限制）、get_week_constraints、get_weekly_prescription、get_periodization_status、update_phase
Garmin 数据	query_metrics（kind=fitness/sport_history/intensity/daily/readiness/personal_records）、get_activities_range
运动员	get_athlete、update_athlete、set_ftp、set_threshold_pace、analyze_ftp_test、refresh_athlete_baseline、refresh_fitness_history、backfill_history、get_onboarding_guide
方法论	get_methodology、update_methodology
比赛	races（action=list/add/update/research）、remove_race
力量训练	sync_strength_session、get_strength_baseline、approve_progression、set_exercise_preference、generate_strength_workout、add_exercise
伤病	diagnose_injury、research_injury、update_injury_status
研究	research_exercise、list_exercises、research_sport
记忆	log_coaching_decision、get_active_decisions、update_decision_status、record_athlete_response、get_response_patterns、resolve_anomaly
审批	propose_coaching_action、list_pending_approvals、approve_proposal、reject_proposal
交互	generate_smart_brief、interactive_check_in

每个工具都带有 MCP 注解（只读 / 破坏性 / 幂等 / 开放世界），并由测试强制验证。

6 个提示词：weekly_planning、morning_brief、injury_assessment、 week_review、onboarding、race_program。

6 个资源：coach://athlete/profile、coach://plan/current、 coach://config/training、coach://coaching/decisions、coach://context/now、 coach://coaching/doctrine（长篇指导准则）。

安全与隐私

所有内容都保留在你的设备上：

• 凭据：GARMIN_EMAIL/GARMIN_PASSWORD 保存在 MCP 客户端配置中，或保存在本地 .env 文件中。Garmin OAuth 令牌会缓存在本地令牌存储目录中（源代码检出目录中的 .garth/；已安装副本使用每用户的 garmin-tokens 目录；可通过 COACH_TOKEN_DIR 覆盖）。
• 健康数据：所有训练指导数据（个人资料、计划、健身历史、睡眠、训练指导记忆）都是数据目录中的本地 JSON 文件。没有后端、遥测或分析。
• 哪些内容会离开你的设备：向 Garmin 自有 API 发送的请求（仅向 Garmin 发送你的凭据/令牌）；MCP 客户端在对话过程中发送给其大模型的内容；以及教练研究比赛、伤病或锻炼时可选的公开网页抓取。除此之外没有其他内容：用于检查 PyPI 更新的 FastMCP 启动横幅已禁用。
• 每个数据目录只对应一位运动员，这是有意的设计。要管理多位运动员，请使用不同的 COACH_DATA_DIR 运行多个独立服务实例。

详情及问题报告方式，请参阅 SECURITY.md。

数据目录

解析顺序：COACH_DATA_DIR 环境变量 → 源代码检出目录中的 data/ → 每用户数据目录（已安装的软件包会在首次运行时创建）。软件包中唯一附带的文件是 methodology.json（安全规则、比赛模板、角色设定）；所有个人数据都在本地创建，绝不会提交到版本库。

高级内容

# HTTP transport (streamable-http) instead of stdio
COACH_TRANSPORT=streamable-http FASTMCP_PORT=8000 garmin-coach-mcp

# Code Mode (search/execute meta-tools instead of 50 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,546 tests; clean checkouts use committed sanitized fixtures)
pip install -r requirements-dev.txt
python -m pytest -q

架构

coach/server.py 从 coach/ 包注册工具（11 个工具模块、纯解析器、类型化的 pydantic 存储层、CTL/ATL/ACWR 健身计算、采用令牌优先认证的 Garmin 客户端，以及可将结构化训练推送到手表的训练构建器）。该项目经历了五个阶段的现代化改造——重建认证、模式层、硬性门槛、分节快照和打包——完整历史及其原因请参阅 docs/UPGRADE_ROADMAP.md。开发规范见 CLAUDE.md。

致谢

所有 Garmin Connect 访问功能——登录、MFA、令牌处理、活动和健康数据，以及训练上传——均由 Ron Klinkien（@cyberjunky）及其贡献者开发的 python-garminconnect（MIT）提供。没有它，就不会有 coach-mcp。

许可证

MIT