mcp-nutrition-db

mcp-nutrition-db is a private MCP service that lets ChatGPT record, correct, and query meal nutrition, training sessions, and nutrition goals. ChatGPT interprets meal photos and conversation context; this service owns the durable, auditable data and calculates daily energy budgets.

The production service is intended to run on the NixOS host kage. It listens only on loopback and is reached from ChatGPT through OpenAI Secure MCP Tunnel, so it does not require an nginx route or a public MCP endpoint.

Project documents

• System design defines architecture, module responsibilities, persistence guarantees, and operations.

• Nutrition log API defines entries, trainings, summaries, goals, activity plans, and errors.

• Fixed food inventory API describes reusable foods, portion resolution, history linking, and USDA-first sourcing.

• Implementation plan is the source of truth for phases, acceptance criteria, progress, and deferred work.

• Exercise and recovery energy-credit policy defines confidence-adjusted training allowance, non-recurring recovery-day credits, bounded surplus repayment, recovery protection, and MCP presentation.

• Local testing explains direct Codex attachment and the temporary Secure MCP Tunnel workflow for ChatGPT Web.

The implementation plan should be updated in the same commit as meaningful implementation milestones. Design changes should be recorded in the decision log before or alongside the code that depends on them.

Related MCP server: Food Facts MCP Server

Current status

The service implements schema v5 and twenty-eight MCP tools, including the reusable food catalog, USDA lookup, portion resolution, and audited history linking. Repository, schema, calendar, MCP process, Streamable HTTP, package, and NixOS evaluation checks pass; see the implementation plan for the exact verified state.

Ordinary meal components reference inventory foods and immutable revisions. Search before creating a food; normalized short names, USDA IDs, and product identifiers are unique even for archived foods. Historical links preserve existing nutrition snapshots instead of recalculating old meals.

USDA lookups use a read-only local database built from checksum-pinned official Foundation, SR Legacy, and FNDDS bulk releases. There are no runtime USDA API calls, keys, or network fallback. Nix packages include the database; other installations set MCP_NUTRITION_USDA_DATABASE to its path. The NixOS override is services.mcp-nutrition-db.usdaDatabase.

Selected USDA records are copied into immutable evidence snapshots in the personal database. Dataset updates change available search results, never existing food revisions or meals. See offline USDA data for coverage, provenance, and the explicit update process.

Development

Enter the pinned environment and run the checks:

nix flake check --print-build-logs

For focused iteration, enter nix develop and run PYTHONPATH=src pytest, ruff check src tests, ruff format --check src tests, or PYTHONPATH=src mypy src. These same checks are enforced by the flake and CI.

Run a loopback development server with disposable state:

nix run . -- serve --database /tmp/mcp-nutrition-db.sqlite3

Create an atomic SQLite online snapshot without stopping the server:

nix run . -- backup \
  --database /tmp/mcp-nutrition-db.sqlite3 \
  --output /tmp/mcp-nutrition-db.backup.sqlite3

The MCP endpoint is http://127.0.0.1:8787/mcp; readiness is available at http://127.0.0.1:8787/healthz. The server refuses a non-loopback HTTP bind by default. See local testing to attach a new Codex session or run the pinned tunnel client for ChatGPT Web.

Garmin scale/workout import, private sops login, connection hints and explicit weight-budget reviews are documented in Garmin sync.