macrofactor-mcp

Purpose

MacroFactor MCP is a locally running "Fueling & Recovery Decision Engine." It combines MacroFactor nutrition data with Garmin training data so users can ask decision-oriented questions to an MCP client, instead of manually comparing across multiple interfaces such as nutrition, sleep, body, and training.

The core questions it tries to answer include: Have I recovered? Is my fueling working? What should change next week?

Main Capabilities

The project provides four flagship workflows, and all examples use synthetic data:

• recovery_check (Have I recovered?): Combines last night's sleep, HRV, body battery, training load, and yesterday's fueling to generate a readiness view.
• daily_briefing (What do today's signals say together?): Presents a day as a whole picture, rather than separate nutrition and training logs.
• weekly_report (What should change next week?): Reviews seven days of nutrition, body weight, training, sleep, and training load.
• nutrition_performance_correlation (Is my fueling working?): Compares nutrition data with the next day's Garmin recovery signals. It reports sample size so that cases with too small a sample or missing data remain visible.

How to Use

1. Install uv, then confirm that the packaged server can start.
2. Export data from MacroFactor, place the .xlsx file in a local directory, and add the following configuration to the MCP client configuration (using absolute paths).
3. Restart the MCP client. The server will import the new workbook on startup. Run setup_check, then ask one of the questions above.
4. If the desktop client cannot find uvx, replace "uvx" with which uvx the absolute path returned.

Garmin Integration: Garmin is optional. To enable it, point GARMINTOKENS to an existing local Garth/Garmin token directory, then run sync_garmin.

Mode selection: You can use MacroFactor only, or MacroFactor + Garmin.

Suitable Scenarios

Suitable for users who want to combine nutrition intake and training recovery data to make judgments, especially those who need to answer questions about recovery status, fueling effectiveness, and the direction of next week's adjustments. The Garmin correlation workflow requires overlapping dates between MacroFactor and Garmin.

Limitations

• Platform support: macOS and Linux; Windows has not been tested.
• Requires Python 3.10 or newer.
• v0.1 requires manually exporting data from MacroFactor and does not connect to the MacroFactor API.
• Correlations are observational and cannot prove that a certain behavior caused a certain outcome.
• Import support follows the current MacroFactor Quick Export and All-Time Data workbook layouts.
• Raw nutrition, body, training, and Garmin data remain in a local DuckDB database, and the server does not upload that database. However, MCP tool results are sent to whatever model or client the server is connected to. Please review that client's data policy and avoid requesting details beyond what you are willing to share.
• This is an unofficial project and is not affiliated with, endorsed by, or supported by MacroFactor or Stronger By Science. It is not medical advice and cannot replace the care of a qualified health professional.
• Released under the MIT License.
• mcp-name: io.github.NasserAlbusaidi/macrofactor-mcp