---
name: food
description: Look up nutrition facts, ingredients, allergens, and scores for packaged foods, or find products that meet nutritional criteria, using the food CLI or the food MCP tools over Open Food Facts data. Use when a question involves calories, sugar, protein, salt, additives, Nutri-Score, NOVA, or a product barcode.
---

# Food nutrition lookup

Read-only data on about 1.9 million packaged foods from an English-language
Open Food Facts snapshot, served at https://nutrition.sh with no API key.

## Pick an interface

1. If the MCP tools `search_products`, `get_product`, and `list_nutrients`
   are available, use them. They carry the same data with typed arguments.
2. Otherwise use the `food` CLI. Check with `food --version`. Install with
   `curl -sSL https://nutrition.sh/install | bash` if it is missing.
3. As a last resort call the HTTP API with curl using the same parameter
   names, and send a descriptive `User-Agent` header.

## Workflow: search, then get

Search returns summaries only. Nutrients, ingredients, and tags come from a
second call with the product code.

```sh
food search "dark chocolate" --limit 10
food get 0081014090553
```

When stdout is not a terminal the CLI prints the API's JSON, so pipe into
`jq` to keep context small:

```sh
food get 0081014090553 | jq '{name, brands, nutrients: [.nutrients[] | {name, per_100g, per_100g_unit}]}'
```

## Filters

All filters combine with AND.

- `--brand`, `--category`, `--country`, `--label`, `--allergen`: normalized
  tags, lowercase with a language prefix, such as `en:snacks`, `en:organic`,
  `en:united-states`, `en:milk`.
- `--nutriscore a` through `e`. `--nova 1` through `4`.
- `--nutrient NAME --min X --max Y`: inclusive range per 100 g. Common names:
  `energy-kcal`, `sugars`, `proteins`, `fat`, `saturated-fat`,
  `carbohydrates`, `fiber`, `salt`, `sodium`. Run `food nutrients <prefix>`
  to find others.
- `--limit 1` to `100`, `--cursor` from the previous page, or `--pages N` to
  fetch and merge N pages in one call.

## Reading nutrient values

- `per_100g` and `per_serving` are expressed in `per_100g_unit`: grams for
  mass nutrients, kJ for `energy`, kcal for `energy-kcal`. So cholesterol
  `0.0625` with unit `g` is 62.5 mg. Use `energy-kcal` for calories.
- `value` and `unit` are the number as printed on the package. Never mix
  them with `per_100g`.
- Many fields are null and `completeness` below 0.5 means sparse data. Say a
  value is missing rather than guessing it.
- Names may contain HTML entities such as `&amp;`.

## Recipes

Low-sugar options in a category:

```sh
food search --category en:breakfast-cereals --nutrient sugars --max 5 --limit 20
```

Compare two products per 100 g: `get` both codes, then read `energy-kcal`,
`proteins`, `sugars`, and `salt` from `nutrients`.

Allergen check: `get` the product and read `.tags.allergen` and
`.tags.trace`, plus `ingredients_text`.

## Limits

The data is a snapshot, not a live mirror, and covers English-language
products. Text search matches every word as a prefix and returns no total
count, so page through results when completeness matters.