BrewForge Docs

Inventory tools

Every tool of the inventory toolset of the BrewForge MCP server and actions API, with access, scope, plan feature and parameters.

Ingredient stock, ingredient catalog, packages, orders and the planner. Every tool here is an MCP tool on https://brewforge.sh/api/mcp?toolsets=inventory and an action at POST /api/v1/actions/<name>. This page is generated from the API itself; see the tool reference for how to read it.

find_stock

Find ingredient stock

readScope: inventory:readAPI reference

List the user's ingredient stock (the inventory: malts, hops, yeasts, misc) with amounts, lots, expiry dates, suppliers and prices. Filter by name, type or status (used up, expiring within 90 days, expired, or low: below max_amount). Amounts: grams for fermentables and hops, the row's own unit for yeast (pkg, ml, g, cells) and misc. Costs are in the user's currency (see get_started). Each row id works as stock in update_stock (change amounts, "I used 50 g of Citra") and remove_stock. To see which ingredients exist (not what is in stock), use find_ingredients. summary gives per type how many rows are in stock / used up and the total weight in grams.

Prop

Type

add_stock

Add ingredient stock

writeScope: inventory:writeAPI reference

Book bought ingredients into the inventory, e.g. "5 kg Pilsner malt" or "100 g Citra 2025 pellets at 13.2% alpha". One call per ingredient. The ingredient is referenced by id or exact name and must be in the user's ingredient picker (find_ingredients lists them; a missing one can be picked from a package with select_package_ingredients or created with save_custom_ingredient). type is inferred from the ingredient; pass it only to narrow an ambiguous name. Amount: fermentables/hops in g (default), kg, oz or lb, stored as grams; yeast in pkg (default), ml, g or cells; misc in the ingredient's unit. If a row of the same ingredient and lot (for hops also form, alpha and harvest year) exists, the amount is added to it and the price becomes the weighted average (merged_into_existing: true). The result has the recorded price with currency. Everything else is optional: lot, expiry date, supplier, price, notes; hops: alpha_acid_pct, form, harvest_year; yeast: manufacturing_date.

Prop

Type

update_stock

Use up, correct or edit stock

writeScope: inventory:writeAPI reference

Change one stock row: take an amount out ("I used 50 g of Citra" → change: -50), add to it (change: 500), set the counted amount (amount: 1200), or edit its lot, expiry date, supplier, price, notes, or hop alpha/form/harvest year. Reference the row by id (from find_stock) or ingredient name; if a name has several rows and only one still has stock, a negative change uses that one. change and amount use the row's unit (grams for fermentables/hops; send unit "kg"/"oz"/"lb" to convert). Stock never goes below 0. To book a new purchase use add_stock (it merges lots); deducting a whole brew's ingredients belongs to the brew tools. Text fields: send "" to clear.

Prop

Type

remove_stock

Remove a stock row

destructiveScope: inventory:writeAPI reference

Delete one stock row from the inventory (e.g. a wrong entry or an old lot that is thrown away). Without confirm: true it only shows the row that would be removed. To record that an amount was used, use update_stock with a negative change instead: a used-up row (amount 0) stays so it can be restocked. The ingredient itself stays in the picker and in recipes.

Needs confirm: true; without it nothing changes and the response previews what would be removed.

Prop

Type

find_ingredients

Find ingredients

readScope: inventory:readAPI reference

Search the ingredient catalog by name and type, with key specs (color, alpha acid, attenuation, ...). Use it to find the exact name or id that add_stock, order items and recipe tools expect. scope "picker" (default) lists what the user can use right now: My Ingredients plus the ingredients chosen from packages. scope "catalog" searches every package BrewForge offers (query required), including ingredients not picked yet (in_picker: false); pick those with select_package_ingredients. This lists ingredients, not stock; find_stock shows amounts in stock.

Prop

Type

save_custom_ingredient

Create or edit an own ingredient

writeScope: inventory:writeAPI reference

Create an ingredient in My Ingredients (when the catalog does not have it), or edit one of the user's own ingredients. Create: leave out ingredient, send type and name plus any specs. Edit: send ingredient (id or name of an own ingredient; find_ingredients with own_only: true lists them) and only the fields to change; the type comes from the ingredient. Catalog ingredients from packages cannot be edited. Ingredients from an import (e.g. a Brewfather import package) can be moved into My Ingredients with move_to_my_ingredients: true (merges with a matching entry there). Fields by type: fermentable kind, color_ebc, potential_ppg, origin, maltster, non_fermentable, max_usage_pct; hop alpha_acid_pct, beta_acid_pct, purpose, origin, harvest_year, aroma; yeast lab, product_id, kind, form, attenuation_min_pct, attenuation_max_pct, temp_min_c, temp_max_c, flocculation, alcohol_tolerance_pct; misc kind, default_unit. All: description. Send "" to clear a text field.

Prop

Type

delete_custom_ingredient

Delete an own ingredient

destructiveScope: inventory:writeAPI reference

Delete one of the user's own ingredients (My Ingredients or an imported one). Without confirm: true it only shows what is affected: its stock rows (deleted with it) and the brews whose recipes use it (they keep the ingredient's name and amounts but lose the link). Catalog ingredients from packages cannot be deleted; to hide one from the picker, use select_package_ingredients with remove.

Needs confirm: true; without it nothing changes and the response previews what would be removed.

Prop

Type

get_ingredient_packages

List or open ingredient packages

readScope: inventory:readAPI reference

Ingredient packages are the catalog: collections of malts, hops, yeasts and misc from one supplier (e.g. "Weyermann"), plus the user's own packages (My Ingredients, imports). Only picked ingredients show in the user's picker for recipes and stock. Without package: lists every package with ingredient counts and how much of it is picked (in_picker all/some/none). With package (id or name): that package's ingredients with key specs and in_picker per ingredient, filterable by type and name. To find which package has an ingredient use find_ingredients with scope "catalog". To pick ingredients use select_package_ingredients.

Prop

Type

select_package_ingredients

Pick ingredients from a package

writeScope: inventory:writesafe to repeatAPI reference

Choose which ingredients of a catalog package show in the user's ingredient picker (and so can be used in recipes, stock and orders). select: "all" adds the whole package (ingredients the supplier adds later included); select: "none" removes all of it; add / remove change single ingredients (ids or exact names within that package, from get_ingredient_packages or find_ingredients; when several packages offer the same ingredient, pick by id). Removing only hides ingredients from the picker: recipes and stock keep their copies. The user's own packages (My Ingredients, imports) are always fully picked.

Prop

Type

get_orders

List orders or open one

readScope: inventory:readPlan feature: ordersAPI reference

Orders are the user's purchasing lists (what to buy from a shop, what is on the way, what arrived). Without order: lists orders, newest activity first, with status, item and arrival counts and costs; filter by status or name. With order (id or name): that order with all its lines (line ids, amounts, units, received, prices) and next_step. Costs are in the user's currency. Line ids are what edit_order_items and receive_order take.

Prop

Type

save_order

Create or edit an order

writeScope: inventory:writePlan feature: ordersAPI reference

Create an order (a purchasing list for one shop) or change one: name, supplier, status, shipping cost, expected delivery date, notes. Create: leave out order and send name (plus optional items to put on it right away). Edit: send order (id or name) and only what changes. Status: "draft" (still to order), "ordered" (placed; its items count as on order in the planner), "partial" (some items arrived), "received" (everything arrived). Setting "ordered" stamps the order date. Setting "received" does NOT book anything into stock: to put arrived items into the inventory use receive_order. To add, change or remove lines later use edit_order_items. To build an order from what the planned brews are short of, use create_order_from_shortages.

Prop

Type

edit_order_items

Add, change or remove order lines

writeScope: inventory:writePlan feature: ordersAPI reference

Change the lines of one order in a single call: add new lines (ingredient by name or id; a line for the same ingredient, form and unit is merged by adding the amounts), update lines (amount, ordered_amount, price_paid from the invoice, estimated_cost, notes) and remove lines. Amounts: fermentables/hops in g (default) or kg (the line keeps g or kg; oz/lb are converted to g); yeast in pkg by default; misc in the ingredient's unit. Prices are per whole line in the user's currency. Lines are referenced by line id or ingredient name. To book arrived lines into stock use receive_order.

Prop

Type

receive_order

Receive an order into stock

writeScope: inventory:writePlan feature: ordersAPI reference

Mark an order's lines as arrived and book them into the ingredient stock ("the order from Hopfen der Welt arrived"). Without items: receives everything still outstanding on the order. With items: only those lines, with an optional amount (default: what is still outstanding, in the line's unit) and price_paid for the line. The result lists stock_changes (each changed stock row before/after). Booking into stock merges into the matching stock row and sets the price per kg / per unit from the line price plus its share of shipping, with the order's supplier on the stock row. Free-text lines are booked into the brewer's own library ingredient of the same name (subscribed or own ingredients, as in the pickers); lines with no such ingredient are marked received but not booked (see note). The order becomes "partial" or "received". Send add_to_stock: false for lines that should not go into the inventory.

Prop

Type

delete_order

Delete an order

destructiveScope: inventory:writePlan feature: ordersAPI reference

Delete one order with all its lines. Without confirm: true it only shows the order that would be deleted. Stock already booked in from it stays in the inventory. A finished order can also simply stay with status "received".

Needs confirm: true; without it nothing changes and the response previews what would be removed.

Prop

Type

get_planner

Plan ingredients for planned brews

readScope: inventory:readPlan feature: inventory_plannerAPI reference

What the planned brews need and what is missing ("what am I short of for my planned brews?"). Lists the brews with status planned and, per ingredient, the amount in stock, on order (orders with status ordered/partial), needed by the planned brews, what is left and what to buy (to_buy), with each brew's share. Default: every planned brew and only the ingredients they use; show: "shortages" for only what to buy, "all" to include stock no planned brew needs. Amounts are in each row's unit (grams for fermentables and hops). To turn the shortages into an order in one step use create_order_from_shortages.

Prop

Type

create_order_from_shortages

Order what the planned brews are short of

writeScope: inventory:writePlan feature: inventory_plannerAPI reference

Put everything the planned brews are short of (the planner's to_buy amounts, after stock and open orders) on an order in one step: a new draft order, or an existing draft order (order). Defaults: all planned brews and all ingredient types; narrow with brews and type. Lines for the same ingredient merge. Returns the order with its lines; when nothing is short, nothing is created. Recipe lines not linked to an ingredient become free-text order lines (see free_text_items); receive_order links them by name when it can. Check get_planner first to see what will be ordered. Afterwards adjust lines with edit_order_items and mark it ordered with save_order.

Prop

Type

On this page