内容
我是否恢复了？我的燃料补充有效吗？下周应该改变什么？
唯一将 MacroFactor 营养与 Garmin 训练数据相结合的 MCP。
MacroFactor MCP 是一个本地燃料补充和恢复决策引擎。给你的 MCP 客户端一个 MacroFactor 导出文件，可选地添加 Garmin，然后询问决策，而不是手动比较营养、睡眠、身体和训练屏幕。
## 快速入门
安装 [`uv`](https://docs.astral.sh/uv/)，然后确认打包的服务器启动：
```bash
uvx macrofactor-mcp
```
从 MacroFactor 导出您的数据，将 `.xlsx` 文件放在一个本地目录中，并将其添加到您的 MCP 客户端配置中。使用绝对路径。
```json
{
"mcpServers": {
"macrofactor": {
"command": "uvx",
"args": ["macrofactor-mcp"],
"env": {
"MACROFACTOR_DATA_DIR": "/绝对路径/to/macrofactor-exports",
"MACROFACTOR_DB_PATH": "/绝对路径/to/macrofactor.duckdb"
}
}
}
}
```
重启 MCP 客户端。服务器在启动时导入新的工作簿。运行 `setup_check`，然后询问以下问题之一。如果桌面客户端无法找到 `uvx`，请将其替换为 `which uvx` 返回的绝对路径。
## 四大核心工作流
以下所有示例都使用合成数据。
### `recovery_check` — 我恢复了吗？
结合昨晚的睡眠、心率变异性（HRV）、身体电池、训练负荷和昨天的燃料补充情况，生成一个恢复情况的视图。
```text
恢复检查：2026-07-08
睡眠：7小时38分钟，评分82；HRV +4 vs 7天平均值
训练负荷：ACWR 1.08（最佳）
昨天：96% 卡路里目标；101% 蛋白质目标
总体：所有系统都正常 — 4个积极信号。
```
### `daily_briefing` — 今天的信号综合情况如何？
将一天的综合情况以一张图片的形式展示，而不是单独的营养和训练日志。
```text
每日简报：2026-07-08
摄入量：2,340 kcal（蛋白质171g / 脂肪72g / 碳水化合物248g）
遵守情况：98% 卡路里 | 101% 蛋白质
身体电池：28 → 83 | 睡眠：7小时38分钟，评分82
训练：高效 | 负载612/568（ACWR 1.08）
```
### `weekly_report` — 下周应该改变什么？
回顾七天的营养、体重、锻炼、睡眠和训练负荷。
```text
每周报告：2026-07-02 至 2026-07-08
平均值：2,315 kcal | 168g 蛋白质
目标达成情况：卡路里 6/7 天 | 蛋白质 7/7 天
训练：4 次 | 睡眠：7小时26分钟 平均值
下周信号：燃料补充一致；保护睡眠后再增加负荷。
```
### `nutrition_performance_correlation` — 我的燃料补充有效吗？
比较营养与次日的 Garmin 恢复信号。它会报告样本量，以便小数据集或缺失的数据集保持可见。
```text
营养 → 性能相关性：28 个配对日
蛋白质 >=90% 目标：次日 HRV 51 vs 45 (+6)
蛋白质 >=90% 目标：睡眠评分 81 vs 76 (+5)
能量赤字日：身体电池 68 vs 75 (-7)
观察：高蛋白质日往往预先带来更好的恢复。
```
## 仅使用 MacroFactor 或 MacroFactor + Garmin
| 模式 | 可用决策 |
|---|---|
| 仅 MacroFactor | 营养、体重、锻炼、`daily_briefing` 和 `weekly_report`。恢复输出使用现有的营养信号。 |
| MacroFactor + Garmin | 所有四种核心工作流，包括睡眠、心率变异性、身体电池、活动和训练负荷。 |
Garmin 是可选的。要启用它，请将 `GARMINTOKENS` 指向现有的本地 Garth/Garmin token 目录，然后运行 `sync_garmin`。
## 平台支持
- macOS 和 Linux
- Windows 未测试
- Python 3.10 或更高版本
## 限制
- v0.1 需要手动导出 MacroFactor 数据；它不连接到 MacroFactor API。
- Garmin 相关工作流需要重叠的 MacroFactor 和 Garmin 日期。
- 相关性是观察性的，而不是证明一种行为导致了另一种结果的证据。
- 导入支持遵循当前的 MacroFactor 快速导出和全时数据工作簿布局。
## 隐私
原始营养、身体、锻炼和 Garmin 数据保留在本地 DuckDB 数据库中。服务器不会上传该数据库。但是，**MCP 工具结果会发送到服务器连接的模型或客户端**。请查看该客户端的数据政策，并避免请求比您想要共享的更多详细信息。
## 免责声明
这是一个非官方项目。它与 MacroFactor 或 Stronger By Science 无关，不受其支持或认可。它不是医疗建议，不能取代合格健康专业人员的护理。
在 [MIT License](LICENSE) 下发布。
mcp-name: io.github.NasserAlbusaidi/macrofactor-mcp
