Brewfather MCP Server

Read-only access to your Brewfather brewing history — batches, recipes, fermentation readings, and inventory — exposed to Claude as MCP tools.

Ask questions like "what was my actual brewhouse efficiency across my last ten all-grain batches" or "compare the FG on my three stouts" without exporting anything by hand.

This server is read-only by design. It can only issue HTTP GET requests. There is no code path in it that can create, modify, or delete anything in your Brewfather account — see Read-only guarantee below.

---

Setup

1. Requirements

• A Brewfather Premium subscription — API access requires it.
• uv, which manages Python for you: brew install uv, or curl -LsSf https://astral.sh/uv/install.sh | sh.
• Claude Code or Claude Desktop.

Python itself does not need to be installed separately; uv handles it.

2. Get the code

git clone <this-repo> brewfather-mcp
cd brewfather-mcp

3. Get a Brewfather API key

1. In Brewfather, go to Settings → API.
2. Press Generate.
3. Tick exactly these three scopes, and nothing else:
   • recipes.read
   • batches.read
   • inventory.read
4. Copy the User ID and the API Key. The key is shown only once — copy it before closing the dialog.

Only one API key exists per Brewfather account at a time. Generating a new one invalidates any other integration already using the old one.

The User ID is short (28 characters). The API key is noticeably longer. If a value looks like it might be in the wrong field, compare the lengths.

4. Run setup

bin/setup

This installs dependencies, creates .env for your credentials, generates the Claude Code registration with the correct path for your machine, offers to register with Claude Desktop, runs the tests, and verifies the connection.

It is safe to re-run at any time. On the first run it will tell you the credentials are missing — put them in .env and run it again:

BREWFATHER_USER_ID=your_user_id
BREWFATHER_API_KEY=your_api_key
BREWFATHER_UNITS=us          # "us" (default) or "metric"
BREWFATHER_CACHE_TTL=900     # seconds

5. Use it

Open the folder in Claude Code, or restart Claude Desktop, then just ask:

• "What was my brewhouse efficiency across my last ten all-grain batches?"
• "Compare the FG on my three stouts."
• "What's the grain bill on batch 47?"
• "How's the current ferment tracking?"

There is no import or sync step. Each question fetches only what it needs.

---

Credential handling

.env is gitignored, and was gitignored before the first commit — no credential has ever been committed to this repository.

• Credentials live only in .env, never in .mcp.json, which is far more likely to be committed by accident.
• The API key is base64-encoded into an auth header once at startup and is never stored in plain text on the client object.
• Credentials never appear in log output, error messages, or tool payloads. An authentication failure reports only that the two variables should be checked.
• bin/setup sets .env to mode 600 (readable only by you).
• The server fails at startup with a clear message if either credential is missing, rather than failing later on the first tool call.

Manual registration

bin/setup does this for you. If you would rather do it by hand, both clients need the absolute path to your checkout.

Claude Code — .mcp.json in the project root (gitignored, since the path differs per machine; see .mcp.json.example):

{
  "mcpServers": {
    "brewfather": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/brewfather-mcp", "run", "brewfather-mcp"],
      "env": {}
    }
  }
}

Claude Desktop — the same block in claude_desktop_config.json:

Platform	Config file location
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

Restart Claude Desktop after editing.

Checking it works

Verify the connection. Costs exactly one API call, prints status only — never the payload, never any part of a credential:

uv run python scripts/smoke.py

Run the test suite. All HTTP is mocked; no test spends a live API call:

uv run pytest

---

Tools

Tool	Parameters	Returns
list_batches	status (Planning|Brewing|Fermenting|Conditioning|Completed|Archived), limit (25), newest_first (true)	Compact rows: id, batch number, name, style, brew date, status, measured OG/FG/ABV
get_batch	batch_id (required), sections (optional list)	Full batch: grain bill with percentages, hop schedule, yeast, mash steps, fermentation schedule, water profile, all measured values
get_batch_readings	batch_id (required), latest_only (false), downsample_to (200)	Reading series plus a derived summary: first/last SG, min/max/mean temp, apparent attenuation, days elapsed
list_recipes	limit (25), name_contains (optional)	Compact rows: id, name, style, type, OG, FG, ABV, IBU, colour
get_recipe	recipe_id (required), sections (optional list)	Full recipe, same shape as get_batch
list_inventory	category (fermentables|hops|miscs|yeasts), in_stock_only (true)	Inventory items with converted amounts and spec figures
analyze_efficiency	limit (15), grain_only (true), volume_basis (fermenter|post_boil)	Per-batch brewhouse efficiency plus mean/median/stdev aggregates, split by batch size
compare_batches	batch_ids (2–5), dimension (grain|hops|water|fermentation|measurements)	Aligned side-by-side table
check_connection	—	Credential check, unit mode, cache statistics

sections vocabulary, shared by get_batch and get_recipe: fermentables, hops, yeast, miscs, mash, fermentation, water, measurements, notes. Omit it to get everything.

Notes on specific tools

list_batches orders by brewDate, not by _id. Brewfather's default _id ordering is not chronological, so "newest first" would otherwise be meaningless.

list_recipes — Brewfather has no server-side name search. name_contains filters after fetching, so it costs a full page walk of limit recipes and can return fewer results than limit. Raise limit when filtering.

list_inventory returns only items you have added to your own inventory or set an amount on. It is not Brewfather's full ingredient database.

get_batch_readings — the derived summary is always computed over the full series, then the returned points are downsampled. The statistics describe every reading taken, not just the ones returned.

---

Units

Brewfather's API returns everything metric. This server converts on the way out, and emits both units on every measurement, because ambiguity about which unit a number is in causes real brewing mistakes:

{"amount_lb": 27.5, "amount_kg": 12.47}

Field type	From	To	Factor
Volume	L	US gal	÷ 3.785411784
Fermentable weight	kg	lb	× 2.20462
Hop / misc weight	g	oz	÷ 28.3495
Temperature	°C	°F	× 9/5 + 32
Gravity	SG	SG unchanged, Plato added	—
Colour	EBC	SRM	÷ 1.97
Bitterness	IBU	IBU unchanged	—
Pressure	bar	psi	× 14.5038

Rounding: volumes and weights to 2 decimals, temperatures to 1, gravity to 3.

BREWFATHER_UNITS selects which system is treated as primary in single-value derived summaries. It does not suppress either unit on an individual measurement — those always carry both.

Which field is stored in which unit

Brewfather stores fermentable amounts in kilograms and hop and misc amounts in grams. This server converts accordingly: weight_from_kg for fermentables and inventory fermentables, weight_from_g for hops, miscs, and their inventory equivalents. Yeast inventory is a count of packs, not a mass, and is passed through unconverted.

✅ Verified against live data. Confirmed empirically against real batches. A representative all-grain batch returned fermentable amounts of 2.72, 2.72, 1.44, 0.57, 0.48, 0.14 — kilograms, totalling 8.07 kg (17.8 lb) for a 6.3 gallon batch — and hop amounts of 33.1 and 28.9, which are grams (1.17 oz and 1.02 oz). Neither reading is plausible under the other unit.

---

Efficiency

analyze_efficiency computes brewhouse efficiency per batch as:

potential_points = Σ over fermentables ( amount_lb × ppg )
og_points        = (measuredOg − 1) × 1000
brewhouse_eff    = (og_points × volume_gal) / potential_points × 100

Which grain bill

Brewfather keeps two grain bills per batch: batchFermentables (what actually went into the kettle) and the nested recipe.fermentables (the recipe as it stands now). This server uses batchFermentables. They diverge whenever a recipe is edited after brewing — in the account this was validated against, two batches differ by up to 1.25 kg, enough to move efficiency by several points. Editing a recipe must not retroactively rewrite what a past batch actually did.

PPG per fermentable

Brewfather stores a potential field on each fermentable (an SG such as 1.037) and separately a yield percentage. This server prefers potential, converting it as (potential − 1) × 1000, because that is the figure Brewfather itself calculates with. When only yield is present, it falls back to 46 × yield/100, the same relationship expressed against sucrose's 46 PPG maximum.

This ordering is not cosmetic: on live data yield is null on every fermentable, and potential is always populated. A yield-first implementation would return nothing at all.

Volume basis

The answer depends entirely on where the volume is measured, so the basis is reported alongside every figure and is selectable:

volume_basis	Field used	Meaning
fermenter (default)	measuredBatchSize, else the recipe's planned batchSize	Volume transferred into the fermenter. Kettle and trub losses are charged against the number.
post_boil	measuredKettleSize	Volume in the kettle at flameout. Excludes transfer losses, so it reads higher.

The default is fermenter, and this was determined empirically rather than assumed. Taking Brewfather's own stored efficiency for 27 real batches and inverting the formula to solve for the volume it must have used reproduces measuredBatchSize wherever one is recorded, and the recipe's planned batchSize wherever one is not. That fallback order is what the code implements.

The choice of basis matters more than the build spec's ±2 point tolerance allows for: on a 5-gallon batch with half a gallon of kettle loss the two bases differ by nearly 7 points. Every result therefore carries volume_basis, volume_source_field, and volume_was_measured, so you can always see which volume produced a number and whether it was measured or planned.

Reconciliation against the Brewfather app

These figures come from validating against a real Brewfather account of 29 batches spanning four years. They are evidence that the formula and volume basis are right — not a claim about what your own numbers will be.

Restricted to all-grain batches, which is the tool's default scope:

All-grain batches reconciled	9 of 9 within 2 points
Mean difference	+0.21 points
Median difference	+0.10 points
Largest single difference	1.80 points

Typical agreement is to within a tenth of a point. The single largest gap, 1.80 points, is on a batch with no measured fermenter volume, where the planned volume stands in.

Each batch result includes brewfather_stored_efficiency and delta_vs_brewfather_points, so any divergence is visible in the output rather than something you have to go looking for.

Batches that are not all-grain

grain_only defaults to True, and that default is doing real work. Across the 16 validation batches containing sugar, fruit purée, honey, or lactose, no single formula reproduces Brewfather's stored efficiency. Three candidate models were tested — counting non-mashed fermentables in the denominator, excluding them, and excluding them while also removing their gravity contribution from the measured OG. The best-fitting model differs from batch to batch, and the best mean absolute error any of them achieves is 4.2 points.

The most likely explanation is that Brewfather's stored figure does not recompute when a recipe is edited after brewing, so those values are partly historical artefacts. Rather than pick a model and present a number that would disagree with the app, this tool excludes such batches by default and lists them under excluded_non_grain_batches. Passing grain_only=False includes them, with contains_non_mash_fermentables flagged on each — treat those figures as indicative only.

A fermentable counts as non-mashed if its type is Sugar, Extract, Juice, Honey, Fruit, or Other, or if Brewfather marks it notFermentable (lactose, rice hulls). Fruit purées are typed "Other" in real data, which is why that type is in the list.

When a batch cannot be computed at all, the result says so with a reason — no measured OG, no grain bill, no volume for the chosen basis — instead of returning a null or silently dropping it from the aggregate.

---

Rate limiting and caching

Brewfather allows 500 calls per hour per API key. That budget disappears quickly if every question re-fetches your full history, so caching is not an optimization here — it is what makes the server usable.

• In-memory TTL cache keyed on the full request URL plus query parameters.
• Completed and archived batches, recipes, and inventory: full TTL (default 15 minutes), since they are immutable in practice.
• Fermenting batches and every /readings endpoint: 60 seconds, since they change during an active ferment.
• analyze_efficiency pulls everything it needs through the include parameter in a single list call per status rather than one fetch per batch.

On a 429, the client reads Retry-After, waits, and retries — up to three attempts, then reports a clean rate_limited error naming the hourly cap. On 5xx it backs off exponentially. On 401 and 403 it does not retry, because the answer will not change.

Errors

Tools return a structured error object rather than raising into the MCP transport:

{"error": "rate_limited", "message": "...", "retry_after_seconds": 120}

Code	HTTP	Meaning
auth_failed	401	Check BREWFATHER_USER_ID and BREWFATHER_API_KEY
missing_scope	403	The key lacks the scope the endpoint needs — the message names it
not_found	404	No such batch, recipe, or inventory item
rate_limited	429	500/hour cap reached
upstream_error	5xx	Brewfather is having a problem
bad_request	400	Malformed parameters

Read-only guarantee

• BrewfatherClient.get is the only method in the package that opens a socket, and it hardcodes the HTTP verb. There is no method that takes a verb as an argument.
• No write or delete scope is referenced anywhere in the codebase.
• tests/test_readonly.py enforces all of this: it scans every source file for mutating HTTP calls and write-scope strings, and drives every tool through a mock transport asserting that only GET reaches the wire.
• Every tool is registered with MCP's read_only_hint annotation, so the client is told the server is a reader before it calls anything.

Requires mcp >= 2.0, where the server class is MCPServer (it was called FastMCP in 1.x).

Pagination

Brewfather uses cursor pagination — there is no offset. Pages are walked by passing the _id of the last item seen as start_after, requesting the maximum page size of 50, and stopping when a page comes back shorter than requested. Every list tool goes through the same helper.

Layout

brewfather-mcp/
├── .env                    # gitignored — your credentials
├── .env.example            # committed — placeholders only
├── .mcp.json               # gitignored — generated by bin/setup
├── .mcp.json.example       # committed — shows the shape
├── bin/setup               # one-command install and registration
├── LICENSE                 # MIT
├── pyproject.toml
├── scripts/smoke.py        # live connectivity check, status only
├── src/brewfather_mcp/
│   ├── server.py           # MCPServer instance and tool registrations
│   ├── client.py           # auth, paging, retry, cache
│   ├── units.py            # metric → US customary
│   ├── models.py           # object shapes and payload projections
│   └── analysis.py         # efficiency, readings, comparison
└── tests/                  # all HTTP mocked

Troubleshooting

"authentication failed" — the User ID or API key is wrong, or they are swapped. The User ID is the short one (28 characters).

"The API key is missing the 'inventory.read' scope" — the key was generated without all three read scopes. Regenerate it in Brewfather with recipes.read, batches.read, and inventory.read all ticked.

"rate_limited" — Brewfather allows 500 calls per hour per key. The server caches aggressively to stay well inside that, but a burst of wide-ranging questions can reach it. Wait for the hourly window to reset.

Tools do not appear in Claude — re-run bin/setup, and restart Claude Desktop. For Claude Code, the session must be started in this folder.

uv: command not found — install uv (see Requirements), then re-run bin/setup.

Contributing

The one rule: no write paths. BrewfatherClient.get is the only method that may open a socket, and the HTTP verb stays a literal. tests/test_readonly.py enforces this and will fail the build if it is broken.

Run uv run pytest before submitting. All HTTP in tests is mocked — please keep it that way, so the suite never spends anyone's API budget.

License

MIT — see LICENSE.

Not affiliated with or endorsed by Brewfather. Using the Brewfather API requires a Brewfather Premium subscription and is subject to Brewfather's own terms of service.