foodos-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@foodos-mcp Scale my chicken recipe to 6 portions with different serving sizes and give macros per portion."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
๐ฝ๏ธ foodos-mcp
Big batch. Different appetites. Macros that add up. โจ
Turn recipes into traceable nutrition numbers, cooked-weight calculations, and portions that fit each eater โ all through the Model Context Protocol (MCP).
Your AI assistant handles the conversation. foodos-mcp handles the math. ๐งฎ
LLMs can help you find dinner, but they can also guess gram weights, invent macros, or split a batch in half when everyone needs a different portion. This server makes those calculations deterministic and auditable, from the first ingredient to the last lunchbox.
โจ Meet your meal-prep math engine
๐ Know where every number came from. Macro values trace to a USDA food ID, an Open Food Facts barcode, or data you supplied.
โ๏ธ Weigh it cooked. Count it correctly. Turn raw ingredient totals into macros per 100 g of the finished batch.
๐ One batch, different portions. Size a serving by a target, a fixed weight, or whatever is left.
๐ฆ Give leftovers a plan. Keep track of portions for tonight and boxes for later.
๐ Keep guesses off the plate. Ambiguous food lookups return candidates for you to choose from.
๐ฅ Raw ingredients โ ๐งฎ Batch macros โ ๐ณ Cooked weight
โ
Macros per 100 g cooked
โ
๐ฝ๏ธ Portions sized for each eater
โ
๐ฆ Leftovers & meal prepOne eater needs enough protein to finish their daily target. Another takes 180 g off the scale. A third takes what is left. Tuesday's lunch gets a box, too. Equal portions are optional. Getting the math right is the whole point. ๐
๐ Get started ยท ๐ See the math ยท ๐งฐ Explore the tools ยท ๐ ๏ธ Contribute
Related MCP server: yes_chef_mcp
๐ Quick start
npx foodos-mcp # stdio, for a local client
npx foodos-mcp --transport http --port 3000Node 22.12 or newer. You need a free USDA API key, which takes about a minute to get at api.data.gov/signup.
๐ฅ๏ธ Connect to Claude Desktop
Add this to claude_desktop_config.json, then restart Claude Desktop.
{
"mcpServers": {
"foodos": {
"command": "npx",
"args": ["-y", "foodos-mcp"],
"env": {
"FDC_API_KEY": "your-key-here",
"FOODOS_CONTACT": "you@example.com"
}
}
}
}FOODOS_CONTACT goes in the User-Agent when the server reads Open Food Facts, which their terms ask for. Everything works without it; you are just anonymous.
๐ A batch in action
Letโs roast 800 g of chicken and follow the numbers all the way to the plate. Every step is checkable. ๐
1. ๐ Find the food. searchFood with "chicken breast raw" returns candidates from USDA. Pick one; the model should show you the list rather than choose. Here it is fdcId 2646170, "Chicken, breast, boneless, skinless, raw".
2. ๐งฌ Get its macros. getFoodMacros returns, per 100 g:
per 100 g | |
Protein | 22.525 g |
Fat | 1.934 g |
Carbohydrate | 0 g |
Energy | 106.034 kcal |
It also reports energySource: "atwater_general_2047". Foundation foods carry no plain energy nutrient at all, only the two Atwater values, and the server tells you which one it used rather than leaving you to wonder.
3. ๐งฎ Total the batch. computeBatchMacros with 800 g of it: 180.2 g protein, 15.5 g fat, 848 kcal.
4. ๐ณ Weigh it after cooking. You roast it and the tray comes out at 600 g. setCookedYield with rawG: 800, cookedG: 600 gives a yield factor of 0.75 and, per 100 g cooked: 30 g protein, 2.6 g fat, 141 kcal.
5. ๐ฝ๏ธ Serve it up. portionBatch with two rules, one fixed weight and one remainder:
Eater | Rule | Weight | Protein | Energy |
A | fixed 180 g | 180 g | 54.1 g | 254 kcal |
B | remainder | 420 g | 126.1 g | 594 kcal |
54.06 plus 126.14 is 180.2, which is the batch. The arithmetic runs at full precision from end to end and only the presentation is rounded, so the reconciliation is exact even where two rounded figures are each a tenth off.
๐ฏ Want a portion that fills a target? Change A's rule to solveForRemaining and give A a daily protein target of 150 g with 100 g already eaten. A gets the 166 g that carries the remaining 50 g of protein, and the response says bindingConstraint: "proteinG" along with where fat and energy landed. If that portion blows A's fat target, the response says so in the residuals rather than leaving you to notice.
๐ Try it yourself: examples/worked-example.ts runs this against the live API with your own key.
๐งฐ The toolbox
๐ Read a recipe. parseRecipe pulls the schema.org data a page publishes for machines. parseIngredientLine splits one line into its parts and flags what is ambiguous, so "1 medium onion" comes back as a size descriptor rather than as 150 g.
๐ Look up nutrition. searchFood, getFoodMacros, lookupBarcode, toGrams.
๐งฎ Calculate the batch. computeBatchMacros, setCookedYield.
๐ฝ๏ธ Portion your plates. portionBatch, the reason this repository exists.
๐ Plan the next batch. planBatchSize, scaleRecipe, shoppingList.
๐ Peek under the hood. foodos://yield-factors and foodos://densities expose the bundled tables so you can see exactly what a calculation was based on. foodos://rate-limit-status shows how much of the hourly budget is left.
๐ฌ Follow the guided workflow. portionABatch walks a client through the whole chain, from a URL to portions on plates.
๐ Ingredients deserve sources. So do numbers.
Hereโs where the data comes from, along with the licensing and caching considerations behind the integrations.
Source | Verdict | Why |
USDA FoodData Central | Primary nutrition source | US public domain under CC0 1.0. Free key from api.data.gov. No caching restriction, so this server caches aggressively. |
Open Food Facts | Secondary, for packaged goods and barcodes | Open data under the ODbL, contents under the DbCL. Their terms ask for a descriptive User-Agent with a contact address, which this server sends. |
Spoonacular | Not integrated | Their terms cap caching at about an hour and then require deletion. That is incompatible with a local store, and a local store is what makes the rate limit survivable. |
Edamam | Not integrated | Their terms prohibit automated programmatic requests intended to collect or save data. An MCP server is exactly that. |
Cooking yields come from the USDA Table of Cooking Yields for Meat and Poultry, Release 2 (CC0), plus rows transcribed by hand from Agriculture Handbook 102 (1975, public domain) for rice, pasta, lentils and oats, each citing its page. Densities are derived from the USDA SR Legacy bulk export, a 6 MB public-domain download that needs no API key, with each row citing the food and portion it came from. A cup of flour is 125 g and a cup of honey is 339 g, which is why volume never converts to weight without knowing the ingredient.
Rice roughly triples in weight when cooked and lentils nearly do. A yield factor is not always below 1, and treating it as though it were would be wrong for half a kitchen.
๐ฆ Keep your API budget happy
FoodData Central runs behind api.data.gov: 1,000 requests an hour per key, on a rolling window, with a 429 when you go over. A single recipe with fifteen ingredients can burn thirty calls between searching and looking up, so this is a real ceiling rather than a theoretical one.
Hereโs how the server keeps the budget visible:
A local counter refuses the call before it leaves the process when the budget is spent, and tells you when it frees up.
Response headers are authoritative. If USDA says 40 requests remain, the local count is corrected to match, because a key shared with another client is further along than this process can know.
The default budget is 800, deliberately under the real 1,000, so a second client does not push you into a 429.
Nothing queues, sleeps or retries. Only you know whether the rest of the work is worth what is left.
Cache hits never count. Lookups are cached for a month, which is allowed without reservation because the data are public domain.
Check foodos://rate-limit-status before a big batch. Set FDC_HOURLY_BUDGET to change the ceiling.
The real answer, when this becomes a problem, is that USDA publishes complete monthly exports of about 6 GiB. A local copy takes the API out of the hot path entirely. That is the v0.2 plan; there is a TODO(bulk-import) in the client pointing at it.
DEMO_KEY works for a first smoke test and is capped at ten requests an hour, which you will hit almost immediately. It is never used as a fallback in code.
โ๏ธ Make it yours
Variable | Default | What it does |
| none | Required for anything that reads USDA data. No default key ships in this repository. |
|
| Requests an hour before the server refuses to make more. |
| repository URL | Contact address sent in the User-Agent, as Open Food Facts asks. |
| platform cache directory | Where cached lookups live. |
|
|
|
โ๏ธ Run it remotely
foodos-mcp --transport http --host 127.0.0.1 --port 3000 --allowed-hosts foodos.example.comThe endpoint is POST /mcp, and GET /healthz answers for a load balancer. It runs stateless, so there is no session affinity to arrange.
There is no authentication in this server, on purpose. Terminate TLS and auth at the reverse proxy and keep the server bound to loopback:
location /mcp {
proxy_pass http://127.0.0.1:3000/mcp;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Connection "";
proxy_buffering off; # streamable HTTP sends server-sent events
proxy_read_timeout 300s;
}Passing --allowed-hosts turns on DNS rebinding protection for the hosts you name.
๐งญ What belongs on the menu
foodos-mcp focuses on recipe and portion calculations. It provides numbers, with no health advice, diet recommendations, or judgments about your plate.
There are no accounts or built-in authentication. The server reads two public food data sources, caches lookups locally, and does the arithmetic.
๐ ๏ธ Build with us
pnpm install
pnpm check # biome, tsc and vitest
pnpm test:coverage
pnpm buildThe test suite runs entirely offline. Every HTTP request is intercepted, and an unhandled one fails the run, so a forgotten network call cannot reach USDA from CI.
Ready to dig in? Read CONTRIBUTING.md before opening a pull request. ๐งโ๐ณ
๐ License
MIT licensed. Fork it, explore it, and build something delicious. See LICENSE.
USDA FoodData Central data are in the public domain. U.S. Department of Agriculture, Agricultural Research Service. FoodData Central, fdc.nal.usda.gov. Open Food Facts data are available under the Open Database License.
Available Tools
12 toolscomputeBatchMacrosARead-onlyIdempotent
Total the macros of a whole batch from its ingredients. Each ingredient needs a nutrition source and a weight. Any ingredient missing either is returned in unresolved with candidate matches and is never dropped or approximated: the totals then carry isComplete false and are a partial sum.
Inputs: ingredients (required), suggestCandidates. Returns: budget, totals, coverage, warnings, +4 more
getFoodMacrosARead-onlyIdempotent
Per-100 g macros for one USDA food id, with its portion weights. Also reports which energy nutrient was used, since Foundation foods report Atwater factors rather than a plain energy value.
Inputs: fdcId (required). Returns: fdcId, budget, per100g, dataType, +5 more
lookupBarcodeARead-onlyIdempotent
Per-100 g macros for a packaged product from Open Food Facts. Community-contributed label transcriptions, so confidence is medium rather than high.
Inputs: barcode (required). Returns: brands, barcode, per100g, fromCache, +2 more
parseIngredientLineARead-onlyIdempotent
Split one ingredient line into quantity, unit, ingredient and preparation note. Reports what is ambiguous instead of resolving it: '1 medium onion' comes back flagged as a size descriptor, never as a weight in grams.
Inputs: line (required). Returns: raw, name, unit, unitRaw, +7 more
parseRecipeARead-onlyIdempotent
Read a recipe from a web page. Returns its title, ingredient lines as written, declared servings and instructions, taken from the schema.org data the page publishes for machines. Fails clearly when a page has no structured data rather than guessing at the markup.
Inputs: url (required). Returns: title, author, finalUrl, fromCache, +6 more
planBatchSizeARead-onlyIdempotent
Work out how much to cook, from an explicit list of who is eating and how much each takes. Size slots by weight or by macros where you can. Sizing a slot as a count of the recipe's declared servings always warns, because 'serves 4' is the author's claim about their own portions and not a measurement of a household meal. Returns the arithmetic so it can be checked.
Inputs: basis (required), slots (required), allowIncomplete. Returns: slots, totals, warnings, arithmetic, +1 more
portionBatchARead-onlyIdempotent
Split a cooked batch into portions that are sized per eater rather than divided equally. Each portion carries its own rule: solve for what an eater still needs today, take a fixed weight, hit a macro target, take the remainder, or set food aside for later. Returns each portion's weight and macros, which constraint decided the weight, and where the other targets landed. Asking for more than the batch holds is an error, never a silent scale-down. Weights are rounded to the gram for reporting, so adding up the portions can differ from the batch by a gram; allocatedG and leftoverG carry the exact figures.
Inputs: portions (required), totalMacros (required), totalCookedG (required), eaters, +1 more. Returns: byEater, portions, warnings, leftoverG, +3 more
scaleRecipeARead-onlyIdempotent
Scale a raw ingredient list. Scaling to a macro target needs the recipe's current totals, from computeBatchMacros: this server does not infer what a recipe contains. Amounts in discrete units such as eggs are reported when they land on a fraction, never rounded here.
Inputs: by (required), ingredients (required). Returns: factor, warnings, arithmetic, ingredients, +1 more
searchFoodARead-onlyIdempotent
Search USDA FoodData Central for a food. Prefer Foundation and SR Legacy results for whole ingredients: they are laboratory-analysed and carry portion weights. Use Branded only for packaged products. Show the user the candidates and let them choose; do not pick silently.
Inputs: query (required), limit, dataType. Returns: query, budget, fromCache, totalHits, +1 more
setCookedYieldARead-onlyIdempotent
Convert batch totals into per-100 g cooked values. Pass the measured cooked weight when you have it. Failing that, pass a yield factor you measured yourself, or a yieldHint to look one up in the bundled USDA tables. A hint matching several rows returns unresolved with candidates rather than choosing one. Note that rice and dried legumes gain weight: their yield factors are above 1.
Inputs: rawG (required), totalMacros (required), cookedG, yieldHint, +1 more. Returns: rawG, basis, status, cookedG, +6 more
shoppingListARead-onlyIdempotent
Aggregate raw quantities across recipes, grouped by USDA food category, with what you have on hand subtracted. Two ingredients merge only when they resolve to the same food.
Inputs: recipes (required), onHand. Returns: budget, groups, warnings
toGramsARead-onlyIdempotent
Convert an amount to grams. Mass units are exact. A volume or a count needs either the food's own USDA portion weights, which you get by passing fdcId, or a sourced density row. When neither is available the answer is unresolved with candidates attached, because a cup of flour and a cup of honey do not weigh the same.
Inputs: unit (required), quantity (required), fdcId, ingredientName. Returns: note, grams, method, unitKind, +6 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 12 tools
Most tools target distinct pipeline stagesโfood lookup, parsing, conversion, batch math, portioning, scaling, and shoppingโso an agent can generally select by input and output. The only mild ambiguities are getFoodMacros vs lookupBarcode (both expose per-100g macros) and planBatchSize vs portionBatch (both reason about eaters), but the descriptions state the identifier/source and pre-cook/post-cook differences clearly.
All tool names use camelCase and most follow a clear verb+object convention: parseRecipe, searchFood, computeBatchMacros, scaleRecipe. shoppingList is a bare noun and toGrams uses a preposition rather than a verb, so the pattern is consistent in style but not perfectly uniform.
Twelve tools is an appropriate, well-scoped size for a food/macro meal-planning server. Each tool covers one distinct operation with no redundant clusters, and the set is large enough to span a full workflow without feeling bloated.
The server covers the complete recipe-to-shopping lifecycle: finding foods, parsing recipe and ingredient input, converting to grams, computing batch macros, accounting for cooked yield, portioning, scaling, and aggregating a shopping list. Dependent tools explicitly reference the outputs they need, and unresolved results return candidates instead of dead-ending.
Maintenance
Related MCP Connectors
Food and nutrition data: search, macros, and comparisons
Food nutrition lookup via natural language, barcode, and image. Database of 1,000,000+ foods.
Proof-backed nutrition for foods, chain menus, barcodes, supplements. Agents add what's missing.
Read recipes, nutrition and inventory, manage ingredients and costs, and render ReciPal labels.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables natural language access to USDA's FoodData Central database with 1M+ foods, supporting search, nutrition facts, food comparison, and daily value calculations.8MIT
- FlicenseNot gradedqualityBmaintenanceEnables AI assistants to search recipes, compose nutritionally balanced meals, optimize weekly meal plans based on macro targets for family members, and generate consolidated grocery lists from a personal recipe database.-
- FlicenseAqualityDmaintenanceEnables LLMs to retrieve verified macronutrient data (calories, protein, carbs, fat) for real ingredients and quantities from USDA FoodData Central, with structured caveats for uncertain matches.8-
- AlicenseAqualityBmaintenanceEnables AI assistants to convert recipe amounts between volume and weight for specific ingredients using measured densities, scale recipes, and convert oven temperatures, with source citations and alternative published values.416 npmMIT