Brewing tools
Every tool of the brewing toolset of the BrewForge MCP server and actions API, with access, scope, plan feature and parameters.
Recipes and brews, brew day, fermentation readings, evaluations and devices. Every tool here is an MCP tool on https://brewforge.sh/api/mcp?toolsets=brewing 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_brews
Find brews
List the user's brews (every batch and recipe idea), newest activity first. Filter by name, batch number, status or tag. Returns compact rows (id, name, batch number, status, style, dates); call get_brew with an id for details. Brews can be referenced by id, batch number or exact name in other tools, so use this when you need to search, not to look up one brew you already know.
Prop
Type
get_brew
Get a brew
One brew with its status, dates, style and planned stats (OG/FG as SG, ABV %, IBU, color EBC), out-of-style warnings, plus actual stats once measured. Heavy sections only on request with include: "recipe" (ingredients with entry ids for update_recipe, mash and fermentation steps; L, g, °C), "measured" (brew-day measurements), "readings" (newest fermentation readings), "notes" (newest notes), "versions" (version history: every version and batch of this recipe), "cost" (ingredient cost from inventory prices, in the user's currency). Reference the brew by id, batch number or exact name.
Prop
Type
find_recipes
Browse the recipe book
The recipe book: one row per recipe (all its versions and batches grouped), newest activity first, with style, version count, times brewed (batches), last brew date and BJCP score. query matches text in the recipe name, its style and the style's BJCP category, so "lager" also finds a German Pils filed under a lager category, but only by text: for a family the brewer defines (e.g. "house lagers"), use tag. sort: recent (default), last_brewed, times_brewed or name. Use it to answer "what have I brewed" or to pick a recipe to brew again (copy_brew). For one recipe's version history call get_brew with include ["versions"]; for individual batches use find_brews.
Prop
Type
create_brew
Create a recipe / brew
Create a new brew from scratch: a recipe idea, or a planned batch when you pass planned_date. Everything but the name is optional; the brewer's default equipment, mash and fermentation profiles fill what you leave out. Reference ingredients, style and profiles by name; unknown names fail with candidates and nothing is created. Returns the new brew with its planned stats (OG/FG as SG, ABV %, IBU, color EBC) and the recipe with entry ids, plus the equipment profile and efficiency it was calculated with. To hit an OG or IBU send target_og (gravity_unit "plato" for °P) / target_ibu: malt and bittering hops are scaled like the recipe editor's targets, no trial and error. Change it afterwards with update_recipe (ingredients, process) or update_brew (name, dates, tags). To start from an existing recipe use copy_brew instead; to import BeerXML/MMuM use import_recipe.
Prop
Type
update_recipe
Edit a brew's recipe
Change a brew's recipe step by step without resending it: add, change, swap or remove ingredients (by name), set batch volume, boil time, efficiency, mash rests, fermentation stages, style, FG override, or load an equipment/mash/fermentation/water profile by name. target_og / target_ibu rescale malt / bittering hops to hit an OG or IBU (the editor's target modes). Send only what changes. Returns the new planned stats (OG/FG as SG, ABV %, IBU, color EBC), out-of-style warnings, the recipe with entry ids and notes on what changed. Example: swap Cascade for Citra → {"brew": "#12", "change_ingredients": [{"ingredient": "Cascade", "replace_with": "Citra"}]}. Name, dates, tags and status are update_brew / set_brew_status. Imported recipes must be converted first (convert_imported_brew).
Prop
Type
update_brew
Rename, date, tag or pin a brew
Change a brew's details (not its recipe): name, description, planned brew day, actual brew date, ready-by date, tags, pin. Send only what changes; null clears a date. Setting planned_date on an idea also makes it "planned" (it gets a batch number), which is how you plan a brew for a day. For other status changes use set_brew_status; for ingredients and process use update_recipe.
Prop
Type
set_brew_status
Change a brew's status
Move a brew through its lifecycle: idea → planned → brewing → fermenting → conditioning → completed → archived. The app's side effects happen as in the UI: planning assigns a batch number, brewing sets the brew date (today unless you pass date), conditioning records its start, completing adds the beer to tap lists set to auto-add. Unusual moves (backwards, skipping steps, archiving early) return needs_confirmation with the app's warning and change nothing; repeat with confirm: true after checking with the user. Brew-day measurements, packaging and cellar moves are separate tools.
Prop
Type
copy_brew
Brew again, new version or copy as new recipe
Start a new brew from an existing one. mode "brew_again" (default): the next batch of the same recipe version, status planned with a new batch number. "new_version": the next version of the recipe (v2, v3, ...) as an idea, to change with update_recipe; version_notes says what changes. "new_recipe": an independent copy under a new name (no version link). It copies the brew as it is now (including earlier update_recipe changes). from accepts a brew (id, batch number) or a recipe (name, recipe id; its newest brew is copied). Pass planned_date to plan the new brew right away. Fails with LIMIT_REACHED when the free plan's brew limit is full.
Prop
Type
share_brew
Turn a brew's share link on or off
Create (enabled: true, default) or remove (enabled: false) the public read-only link to a brew's recipe and results. Anyone with the link can view the recipe and copy it to their own BrewForge account (there is no sharing with one specific person: give them this link); removing the link makes it stop working. Calling it again with enabled: true keeps the existing link. Returns share_url (absent when off).
Prop
Type
convert_imported_brew
Make an imported recipe editable
Imported recipes (BeerXML, Brewfather, ...) keep the source program's numbers (OG, IBU, volumes) and can't be edited until they use BrewForge's own calculations. mode "convert" (default) switches this brew to BrewForge calculations in place; "fork" keeps the import untouched and creates a new editable version. Afterwards the stats may differ slightly from the imported ones. Returns the editable brew; then use update_recipe on it.
Prop
Type
import_recipe
Import a recipe (BeerXML or MMuM)
Import recipes from file content: BeerXML (<RECIPES>... from BeerSmith, Brewfather, Little Bock etc., one or more recipes) or MMuM JSON (Maische Malz und Mehr / Kleiner Brauhelfer). Each recipe becomes a new idea in the recipe book that keeps the source program's numbers; call convert_imported_brew before editing one with update_recipe. Pass the file's text as content; format is detected when omitted. MMuM files without batch volume or brewhouse yield need batch_volume_l / efficiency_pct (the error says which).
Prop
Type
export_brew
Export a brew (BeerXML, JSON, PDF sheets)
Export one brew. "beerxml" (recipe for other brewing software) and "json" (everything BrewForge stores, incl. measurements and readings) return the file text in content. The printable sheets "recipe_pdf", "brewday_pdf" (brew-day checklist) and "fermentation_pdf" (log sheet) return a download_url that works without login for 15 minutes; give it to the user, don't fetch it yourself unless you need the PDF bytes.
Prop
Type
delete_brew
Delete a brew
Permanently delete one brew with its readings, notes, evaluations and cellar stays (planned ones too). Without confirm: true it only returns what would be deleted (deleted_with_it) and what stays (devices are detached, tap list entries stay as typed-in beers). Refused while the cellar still holds beer of it (a keg with volume or filled bottles/cans): empty or free those first. To keep the brew out of lists without deleting it, set its status to archived instead.
Needs confirm: true; without it nothing changes and the response previews what would be removed.
Prop
Type
get_brew_day_plan
Get the brew day plan
What to do on brew day, as the app's brew day tab computes it: water volumes (strike/sparge in L), strike temperature (°C), water additions, grain bill, mash steps, boil time, hop and other additions in order, yeast and pitching temperature, and every brew day measurement with its target and the value recorded so far (measurements[].field is the parameter name for record_brew_measurements). Once measurements exist it also returns the batch efficiencies (mash, brewhouse, Sudhausausbeute in %) next to the planned ones. Read-only. Reference the brew by id, batch number or exact name.
Prop
Type
record_brew_measurements
Record brew day measurements
Record what was measured on brew day or at the end of fermentation: strike water, mash pH, pre-boil gravity/volume, boil time, post-boil volume, OG, fermenter volume, pitching temperature, final gravity, peak fermentation temperature. Send only the values you have: a value you send replaces the stored one, the others stay as they are, null clears one. Gravities default to SG (gravity_unit "plato" for °P), temperatures to °C, volumes are litres. Returns the recorded values, how each compares with its target, and the batch values the app derives (mash/brewhouse efficiency %, ABV, attenuation). For gravity readings during fermentation use log_fermentation_reading instead; this does not change the brew status (set_brew_status moves it to fermenting). Targets: get_brew_day_plan.
Prop
Type
deduct_brew_ingredients
Deduct a brew's ingredients from stock
Take the ingredients a brew uses out of the inventory, as "Deduct from inventory" on the brew day tab does: each recipe ingredient is matched to a stock lot by name (hops also by form and alpha acid) and the recipe amount is deducted; the brew remembers what was deducted, so it is never deducted twice. Default: every ingredient with enough stock. ingredients limits it to some (names as in the recipe); naming an ingredient also deducts it when the stock is short (the lot goes to 0). dry_run: true only shows what would happen. undo: true puts deducted ingredients back into stock (all, or the named ones). Amounts in g for fermentables and hops, else the recipe unit.
Prop
Type
log_fermentation_reading
Log a fermentation reading
Add a fermentation reading (gravity, temperature, pH, pressure and/or a comment) to a brew, as from a hydrometer or refractometer check. Gravity defaults to SG (send gravity_unit "plato" for °P), temperature to °C. Stored in canonical units (SG, °C, psi); it shows up in the brew's fermentation chart. Several readings at once: send readings: [{gravity, temp, at}, ...] instead of the single fields. To correct a reading, send reading_id (ids come from get_fermentation) with only the fields to change; null clears a field. The final gravity of a finished beer is recorded with record_brew_measurements (fg). Reference the brew by id, batch number or exact name.
Prop
Type
get_fermentation
Get fermentation status and readings
How a brew's fermentation is going, as its fermentation tab shows it: OG, expected FG, current gravity, apparent attenuation and ABV so far, whether the gravity is stable (finished), the current speed and the projected time to reach FG, plus the newest readings with their ids (for corrections with log_fermentation_reading reading_id, or delete_fermentation_readings). Use it to answer "is it done?": state "stable" means the gravity changed at most 0.001 over the last day. All gravities in SG, temperatures in °C.
Prop
Type
delete_fermentation_readings
Delete fermentation readings
Delete one or more fermentation readings of a brew by id (e.g. a wrong hydrometer entry or sensor outliers). Without confirm: true it only lists what would be deleted. To fix a value instead, use log_fermentation_reading with reading_id. Reading ids come from get_fermentation.
Needs confirm: true; without it nothing changes and the response previews what would be removed.
Prop
Type
plan_carbonation
Plan carbonation (priming sugar or keg pressure)
Work out how to carbonate a brew and save the plan on its fermentation tab, calculated as the app does it. method "priming" (default): grams of priming sugar for the beer volume, from target CO2 volumes, sugar type and beer temperature (default: the peak fermentation temperature). method "force_carbonation": regulator pressure (psi and bar) for the target CO2 at the serving temperature. Without target_co2_volumes it keeps the saved target or uses the style's typical value. The beer volume is the packaged volume, else the measured fermenter volume minus losses, else the planned volume; send beer_volume_l to override. Temperatures default to °C. Calling it again with only some fields keeps the rest of the saved plan.
Prop
Type
save_brew_note
Add or edit a brew note
Add a timestamped note to a brew's log (what happened, a problem, an adjustment, a tasting impression, a reminder), or edit one. To add, send brew and text (type defaults to "note", time to now). To edit, also send note_id (from list_brew_notes) and only the fields to change. Measurements belong in record_brew_measurements or log_fermentation_reading, not in notes.
Prop
Type
list_brew_notes
List a brew's notes
The notes of a brew's log, newest first, with their ids (for save_brew_note note_id or delete_brew_note). Filter by type or phase.
Prop
Type
delete_brew_note
Delete a brew note
Delete one note from a brew's log. Without confirm: true it only shows the note that would be deleted.
Needs confirm: true; without it nothing changes and the response previews what would be removed.
Prop
Type
set_brew_custom_fields
Set custom field values on a brew
Fill in the brewer's own custom fields on a brew (fields they defined in settings, e.g. "Water source" or "Hop lot"). values maps field name (or id) to its value, e.g. {"Water source": "tap", "Mash tun loss L": 1.2}; null clears a value. Send values: {} to only list the fields with their type, allowed choices and current values. Defining new fields is not done here.
Prop
Type
rate_brew
Rate a brew (quick star rating)
Give a brew a quick rating: 1-5 stars (half stars allowed) with an optional comment, as the evaluations tab's star rating. Example: "rate the porter 4 stars, a bit thin" → {brew: "Porter", stars: 4, comment: "A bit thin"}. Each call adds a rating; send evaluation_id to change an existing one. For a full BJCP or Lagerbernd scoresheet use save_scoresheet. Needs a plan with evaluations (Pro).
Prop
Type
save_scoresheet
Fill in a BJCP or Lagerbernd scoresheet
Start or fill in a full tasting scoresheet for a brew. BJCP (default): section scores (aroma 0-12, appearance 0-3, flavor 0-20, mouthfeel 0-5, overall 0-10; total out of 50), comments per section and off-flavors. Lagerbernd (sheet: "lagerbernd"): nine-step scales in ratings (total out of 60, German school grade), intensities and notes. Without evaluation_id it creates a new sheet with what you send; with evaluation_id (from list_evaluations) it updates only the fields you send. Returns the total score. For a quick star rating use rate_brew. Needs a plan with evaluations (Pro).
Prop
Type
list_evaluations
List a brew's ratings and scoresheets
All tastings of a brew, newest first: your quick star ratings, BJCP sheets (score out of 50) and Lagerbernd sheets (out of 60), plus sheets external evaluators submitted through the public evaluation link. Also says whether that link is on and its URL. Ids are for rate_brew / save_scoresheet (evaluation_id) and delete_evaluation.
Prop
Type
delete_evaluation
Delete a rating or scoresheet
Delete one evaluation of a brew: your star rating or scoresheet, or one an external evaluator submitted. Without confirm: true it only shows what would be deleted. Ids come from list_evaluations.
Needs confirm: true; without it nothing changes and the response previews what would be removed.
Prop
Type
set_evaluation_link
Turn the public evaluation link on or off
The public evaluation link lets friends or judges rate a brew without an account (star rating, BJCP or Lagerbernd sheet); their sheets show up in list_evaluations. enabled: true returns the link (keeps the existing one; new_link: true replaces it so the old URL stops working). enabled: false turns it off. Turning it on needs a plan with evaluations (Pro).
Prop
Type
list_devices
List fermentation devices
The brewer's hydrometers and sensors (iSpindel, Tilt, RAPT Pill, GravityMon, Plaato Airlock, ...) with the brew each one logs to, its last gravity/temperature/battery and when it was last seen. Send device to see that one device's raw data log (newest first), e.g. to check whether it is sending. Gravities in SG, temperatures in °C.
Prop
Type
add_device
Add a fermentation device
Register a hydrometer or sensor so it can send readings: returns the webhook URL to enter in the device (BrewBrain: the token) and setup_steps saying what to enter where. The URL contains the device's secret key and is shown only here, so pass it on to the brewer. Then attach the device to a brew with update_device (brew). Types: ispindel, tilt, tilt_bridge (Tilt Pi / bridge; its Tilts appear by themselves), rapt, hydrom, gravitymon, brewbrain, plaato_airlock. Custom streams are set up in the app.
Prop
Type
update_device
Attach a device to a brew or change its settings
Attach a device to a brew so its readings are logged there (brew: the brew), detach it (brew: null), rename it, or set its gravity calibration offset (added to every gravity it sends; -0.05 to +0.05 SG). A device logs to one brew at a time; attaching it moves it (also off a keg) and moved_from names where it was. Send only what changes.
Prop
Type
delete_device
Delete a device
Remove a device and its raw data log; readings it already logged to brews stay. Its webhook URL stops working. Without confirm: true it only shows what would be deleted. To stop logging to a brew but keep the device, use update_device with brew: null.
Needs confirm: true; without it nothing changes and the response previews what would be removed.
Prop
Type