nutrition-mcp

A local-first nutrition tracker exposed as an HTTP MCP server for Hermes. SQLite is the source of truth for foods, recipes, and meal history; the agent does not need to memorize nutrition facts.

Data Model

The catalog separates a generic food from the products that can satisfy it:

• Food type: a generic concept such as mozzarella, tuna, or pickles.
• Food product: nutrition for a specific product or brand, always stored per 100 g with a usual portion name and weight.
• Brand: stored on a product, such as Milbona.
• Retailer: a searchable relationship, such as Lidl; one product may be linked to multiple retailers.
• Alias: an exact phrase for either a product, recipe, or generic food type.
• Recipe: a reusable set of foods and/or nested recipes with an optional measured yield.
• Meal entry: an immutable nutrition snapshot plus quantity, grams, per-100g facts, recipe components, and recipe adjustments.

For example, a Mozzarella food type can contain several branded products. If the Milbona product is sold at Lidl and is the default:

• mozzarella resolves to the default Milbona product.
• milbona mozzarella resolves from its brand and food-type relationship.
• lidl mozzarella resolves from its retailer and food-type relationship.
• All three point to one concrete product for logging; other mozzarella products remain available by their own aliases or IDs.

Resolution is conservative. Exact product aliases are checked first, then generic aliases/defaults, then exact relationship phrases. Ambiguous relationship phrases fail instead of selecting an arbitrary product.

Product and food-type notes, aliases, brands, retailers, and names are searchable. Notes are useful for details such as low moisture, only sold at Lidl, or the jar with the green lid.

Nutrition Rules

Use add_food_product for all new packaged foods and ingredients. It requires:

• all nutrition facts per 100 g;
• usual_portion_grams;
• usual_portion_name, such as 1 slice, 1 piece, or usual serving.

The older add_food tool remains available for backward compatibility and unusual serving-only data. audit_foods lists migrated or legacy foods that still lack a reliable weight or per-100g facts. Repair those with update_food_product.

Tracked nutrients are calories, protein, carbs, fat, fiber, sugars, saturated fat, and salt. salt_g means grams of salt from the nutrition label, not milligrams of sodium.

Historical entries always keep their stored snapshots when products, defaults, or recipes change later.

MCP Endpoint

• URL: http://HOST:8765/mcp
• Transport: Streamable HTTP through FastMCP
• Health endpoints: GET / and GET /health

If MCP_TOKEN is set, every HTTP request must include:

Authorization: Bearer <token>

PUBLIC_HOSTS is a comma-separated list of hostnames or IP addresses accepted by MCP DNS-rebinding protection. Do not include a scheme or port.

Tools

Food products:

• add_food_product, update_food_product, get_food, search_foods, list_foods
• add_food, update_food for backward compatibility
• add_alias, delete_food, audit_foods

Generic food catalog:

• add_food_type, update_food_type, get_food_type, search_food_types
• add_food_type_alias, assign_food_to_type, set_default_food
• add_retailer, link_food_retailer, unlink_food_retailer, list_retailers

Recipes:

• add_recipe, update_recipe, get_recipe, search_recipes, delete_recipe

Logging and history:

• log_food, log_recipe
• get_day, get_entries, get_weekly_report
• update_entry, bulk_update_entries, delete_entry, finalize_day
• list_aliases, health

Catalog Example

Create the generic type first:

{
  "name": "Mozzarella",
  "aliases": ["mozzarella", "mozz"],
  "notes": "Generic mozzarella used on pizza"
}

Then create a branded product with per-100g nutrition and a usual portion:

{
  "name": "Mozzarella",
  "brand": "Milbona",
  "food_type_alias": "mozzarella",
  "kcal_per_100g": 250,
  "protein_g_per_100g": 18.5,
  "carbs_g_per_100g": 2.0,
  "fat_g_per_100g": 19.0,
  "fiber_g_per_100g": 0,
  "sugars_g_per_100g": 1.0,
  "saturated_fat_g_per_100g": 13.0,
  "salt_g_per_100g": 0.6,
  "usual_portion_grams": 40,
  "usual_portion_name": "pizza portion",
  "aliases": ["milbona mozzarella"],
  "retailers": ["Lidl"],
  "make_default": true,
  "notes": "Low-moisture bag normally used for pizza"
}

After this, all of these log the same product:

{"alias": "mozzarella", "grams": 60}

{"alias": "milbona mozzarella", "grams": 60}

{"alias": "lidl mozzarella", "grams": 60}

Use set_default_food to change which branded product a generic alias resolves to. Existing meal entries are unchanged.

Recipes And Nested Recipes

Recipe items may target either a food or another recipe. A nested recipe must have a positive yield_grams, because the parent needs to know what fraction is used. Cycles are rejected.

Example dough recipe:

{
  "name": "Pizza dough batch",
  "aliases": ["pizza dough"],
  "yield_grams": 600,
  "ingredients": [
    {"alias": "flour", "grams": 400},
    {"alias": "olive oil", "grams": 20}
  ]
}

Use 165 g of that recipe inside a pizza:

{
  "name": "Tuna pizza",
  "aliases": ["tuna pizza"],
  "yield_grams": 285,
  "ingredients": [
    {"recipe_alias": "pizza dough", "grams": 165},
    {"alias": "tuna", "grams": 60},
    {"alias": "mozzarella", "grams": 60}
  ]
}

Recipe responses include direct_items and fully flattened ingredients. Logs snapshot the flattened components and source paths, so the complete history remains understandable after later recipe edits.

One-off recipe changes are normalized and stored in the entry:

{
  "alias": "tuna pizza",
  "adjustments": [
    {"alias": "mozzarella", "delta_grams": 20}
  ]
}

Each stored adjustment records the original request and before/after/delta quantities and grams. Updating the logged recipe quantity scales those snapshots consistently.

Correcting Entries

update_entry accepts either quantity or grams for one entry. bulk_update_entries applies several corrections atomically:

{
  "date": "2026-07-17",
  "updates": [
    {"entry_id": 104, "grams": 85},
    {"entry_id": 105, "scale_factor": 0.9},
    {"entry_id": 107, "quantity": 2, "note": "Corrected from photo"}
  ]
}

Each item may contain only one of quantity, grams, or scale_factor. If any correction is invalid, the entire request is rolled back.

Automatic Database Migration

At startup the server checks schema_meta. Schema 1-3 databases are upgraded automatically to schema 4 before MCP tools are registered.

The migration:

1. Creates a consistent SQLite backup under /data/backups.
2. Applies all schema and data changes in one transaction.
3. Preserves food and recipe aliases, searchable notes, recipes, entries, and historical macro snapshots.
4. Creates generic food types and portions for existing foods when the source data supports them.
5. Validates row counts, historical totals, foreign keys, and PRAGMA quick_check.
6. Updates the schema version only after validation succeeds.

Foods without a known serving weight are preserved in legacy mode as needs_review; the migration never invents grams or per-100g values. The /health result reports migration status and review counts.

Data Paths

Inside the container:

• SQLite DB: /data/nutrition.db
• Migration backups: /data/backups
• Daily Markdown: /data/exports/daily/YYYY-MM-DD.md
• CSV: /data/exports/csv/YYYY-MM-DD.csv
• JSON: /data/exports/json/YYYY-MM-DD.json

CSV and JSON exports include grams, amount source, per-100g nutrition, and persistent recipe adjustments.

Local Development

py -3.12 -m venv .venv
.\.venv\Scripts\python -m pip install -e ".[test]"
.\.venv\Scripts\python -m pytest
.\.venv\Scripts\python -m app.main

Test the local endpoint:

curl -H "Authorization: Bearer change-me" http://localhost:8765/health

Docker Compose

The included compose file builds locally and persists the database in ./data:

docker compose up -d --build
docker compose logs -f nutrition-mcp

For Unraid, use a host path instead of the relative volume:

services:
  nutrition-mcp:
    image: ghcr.io/ispas-catalin/nutrition-mcp:0.5.0
    container_name: nutrition-mcp
    restart: unless-stopped
    ports:
      - "8765:8765"
    environment:
      DATA_DIR: /data
      TZ: Europe/Bucharest
      MCP_TOKEN: "replace-with-a-long-random-token"
      PUBLIC_HOSTS: "192.168.1.142,nutrition-mcp"
      HOST: 0.0.0.0
      PORT: 8765
    volumes:
      - /mnt/user/appdata/nutrition-mcp:/data

After replacing the token:

docker compose pull
docker compose up -d
curl -H "Authorization: Bearer YOUR_REAL_TOKEN" http://192.168.1.142:8765/health

Unraid Add Container

• Name: nutrition-mcp
• Repository: ghcr.io/ispas-catalin/nutrition-mcp:0.5.0
• Network Type: bridge
• Port: host 8765 to container 8765 TCP
• Path: /mnt/user/appdata/nutrition-mcp to /data
• TZ=Europe/Bucharest
• MCP_TOKEN=<long random token>
• PUBLIC_HOSTS=192.168.1.142,nutrition-mcp
• WebUI: http://[IP]:[PORT:8765]/

Hermes MCP Config

mcp_servers:
  nutrition:
    url: "http://192.168.1.142:8765/mcp"
    headers:
      Authorization: "Bearer <REAL_MCP_TOKEN>"

Detailed agent behavior and call examples are in HERMES_AGENT_INSTRUCTIONS.md.

Security Notes

• Use a strong token and keep port 8765 on the trusted LAN; do not expose it directly to the internet.
• Keep /data private because it contains meal history and nutrition preferences.
• No arbitrary SQL tool is exposed.
• Deletes require exact IDs and refuse unsafe referenced records.
• Back up /mnt/user/appdata/nutrition-mcp before major host changes even though schema migrations create their own database backup.