macrofactor-mcp

我恢复好了吗？我的补给有效吗？下周应该做哪些调整？ 唯一融合 MacroFactor 营养数据与 Garmin 训练数据的 MCP。

MacroFactor MCP 是本地补给与恢复决策引擎。向你的 MCP 客户端提供 MacroFactor 导出文件，还可以选择添加 Garmin 数据，然后提出一个决策问题， 无需再手动对比营养、睡眠、身体和训练界面。

快速开始

安装 uv，然后确认打包后的服务可以启动：

uvx macrofactor-mcp

从 MacroFactor 导出数据，将 .xlsx 文件放入一个本地目录， 然后将以下内容添加到 MCP 客户端配置中。请使用绝对路径。

{
  "mcpServers": {
    "macrofactor": {
      "command": "uvx",
      "args": ["macrofactor-mcp"],
      "env": {
        "MACROFACTOR_DATA_DIR": "/absolute/path/to/macrofactor-exports",
        "MACROFACTOR_DB_PATH": "/absolute/path/to/macrofactor.duckdb"
      }
    }
  }
}

重启 MCP 客户端。服务会在启动时导入新的工作簿。运行 setup_check，然后提出以下问题之一。如果桌面客户端找不到 uvx，请将 "uvx" 替换为 which uvx 返回的绝对路径。

四大核心工作流

以下示例均使用合成数据。

recovery_check — 我恢复好了吗？

结合昨晚的睡眠、HRV、身体电量、训练负荷和昨天的补给情况，呈现准备状态。

Recovery Check: 2026-07-08
Sleep: 7h 38m, score 82; HRV +4 vs 7-day average
Training load: ACWR 1.08 (optimal)
Yesterday: 96% calorie target; 101% protein target
Overall: All systems go — 4 positive signals.

daily_briefing — 今天的各项信号综合起来说明了什么？

将当天的情况整合呈现，而不是分开展示营养和训练记录。

Daily Briefing: 2026-07-08
Intake: 2,340 kcal (P 171g / F 72g / C 248g)
Adherence: 98% calories | 101% protein
Body Battery: 28 → 83 | Sleep: 7h 38m, score 82
Training: Productive | Load 612/568 (ACWR 1.08)

weekly_report — 下周应该做哪些调整？

回顾 7 天的营养、体重、锻炼、睡眠和训练负荷。

Weekly Report: 2026-07-02 to 2026-07-08
Average: 2,315 kcal | 168g protein
On target: calories 6/7 days | protein 7/7 days
Training: 4 sessions | Sleep: 7h 26m average
Next-week signal: fueling was consistent; protect sleep before adding load.

nutrition_performance_correlation — 我的补给有效吗？

比较营养数据与次日 Garmin 恢复信号。报告样本量，让数据集较小或缺失的情况一目了然。

Nutrition → Performance Correlation: 28 paired days
Protein >=90% target: next-day HRV 51 vs 45 (+6)
Protein >=90% target: sleep score 81 vs 76 (+5)
Energy deficit days: body battery 68 vs 75 (-7)
Observation: higher-protein days tended to precede better recovery.

仅使用 MacroFactor 或同时使用 MacroFactor 和 Garmin

模式	可用决策
仅使用 MacroFactor	营养、体重、锻炼、daily_briefing 和 weekly_report。恢复报告会使用现有的营养信号。
MacroFactor + Garmin	全部四大核心工作流，包括睡眠、HRV、身体电量、活动和训练负荷。

Garmin 为可选项。要启用它，请将 GARMINTOKENS 指向现有的本地 Garth/Garmin 令牌目录，然后运行 sync_garmin。

平台支持

• macOS 和 Linux
• Windows 尚未测试
• Python 3.10 或更高版本

限制

• v0.1 需要手动导出 MacroFactor 数据；不会连接 MacroFactor API。
• Garmin 相关分析工作流需要 MacroFactor 和 Garmin 的日期范围有重叠。
• 相关性分析基于观察结果，并不能证明某种行为导致了另一种结果。
• 导入支持遵循当前 MacroFactor Quick Export 和 All-Time Data 工作簿布局。

隐私

原始营养、身体、锻炼和 Garmin 数据会保留在本地 DuckDB 数据库中。服务不会上传该数据库。不过，MCP 工具的结果会发送给服务所连接的任何模型或客户端。请查看该 客户端的数据政策，并避免请求超出你愿意分享范围的详细信息。

免责声明

这是一个非官方项目，与 MacroFactor 或 Stronger By Science 无关，也未获其认可或支持。 本项目不提供医疗建议，也不得替代合格健康专业人员提供的护理。

根据 MIT 许可证发布。

mcp-name: io.github.NasserAlbusaidi/macrofactor-mcp