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.

Related MCP server: mcp-mealie

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:

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

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.

analyze_attenuation — see Attenuation below. It only has data to work with where a Final Gravity was recorded on the batch; pass include_incomplete=True to fall back to fermentation readings, which is a different kind of number and is labelled as one.

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}

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:

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:

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.

Attenuation

analyze_attenuation answers one question: when a beer "misses FG," is that the fermentation falling short, or the yeast library's attenuation figure being optimistic? It answers it from measured batches rather than from manufacturer claims.

apparent_attenuation_pct = ((OG - FG) / (OG - 1)) * 100
attenuation_delta        = measured AA - the attenuation Brewfather stores for that strain
predicted_fg_delta_pts   = (FG - recipe target FG) * 1000

Worked reference, the case the test suite pins: OG 1.047, FG 1.014 gives (47 − 14) / 47 = 70.2% apparent.

Mash temperature is not optional

Every attenuation figure carries the saccharification rest that produced it. Apparent attenuation is a property of the yeast and the wort it was given, so a single number per strain is meaningless without the mash temp beside it — the same strain at 145 °F and at 158 °F is two different results.

Brewfather leaves name empty on most mash steps, so the rest is found by temperature and duration rather than by label: mash-outs and sparge steps are discarded, then the longest rest between 60 °C and 72 °C wins. Cider and mead recipes carry a placeholder step at 0 °C, which is ignored rather than reported as a 32 °F mash.

Where the final gravity comes from

This is the whole difficulty. Three sources exist and they are not interchangeable, so every batch carries an explicit fg_source:

Brewfather's own attenuation figure is not a measurement when no FG was entered. It falls back to the recipe's estimatedFg, which makes it a restatement of the prediction rather than a test of it. It is surfaced as brewfather_reported_attenuation with brewfather_attenuation_is_estimated: true, and it never drives a computed figure.

Inferring a terminal gravity from readings

With include_incomplete=True, a batch with no recorded FG falls back to its reading series. Neither the last point nor the minimum is safe: Tilts get moved into the next batch while the old one is still open, which leaves fresh wort at the end of a finished series, and a single bad sample mid-crash leaves an impossible low in the middle. So readings at or above OG are discarded as a different fermentation, and the median of the final tenth of what remains is taken as terminal.

The spread across that tail window decides whether the figure is trustworthy. A tail still moving by more than 2 gravity points is a relocated or failing sensor at least as often as it is a gravity, so it is published with fg_is_reliable: false and held out of every aggregate under excluded_for_unsettled_readings.

The Tilt offset is reported, never applied

A Tilt reads high against a benchtop densitometer. Where a figure comes from Tilt readings, the raw number stands as apparent_attenuation_percent, and the correction appears beside it as apparent_attenuation_tilt_corrected_range (backing out 5–6 gravity points), with a tilt_offset_note saying so.

The offset is not a constant — it varies by hydrometer and by batch — which is exactly why it is never folded into the headline figure. Because a raw Tilt figure understates apparent attenuation by roughly twice the offset in percentage terms, a reading-derived number is a floor, not a best estimate. Any aggregate containing one carries a basis_note saying how many of its figures rest on raw readings.

Batches held out of the averages

Two kinds, both still present in the per-batch rows:

• Unfermentables — lactose, or grain Brewfather marks notFermentable that still carries gravity. Their sugar raises FG without the yeast having underperformed. Listed under excluded_for_unfermentables with has_unfermentables: true on the batch.

• Unsettled readings — as above.

The notFermentable flag alone is not the test. Rice hulls carry it too, and they are a lauter aid with a potential of exactly 1.000 — no gravity, so no effect on attenuation. Only an unfermentable that actually contributes gravity points counts.

Reading the aggregate

Per group (strain, style, or nothing): count, mean, median, min, max, the mean and median attenuation_delta, the mash temperature range the group spans, and a suggested_library_value — the median measured attenuation rounded to a whole percent, ready to paste into the Brewfather yeast entry.

The delta is the headline. Grouped by yeast, the tool also emits a delta_reading: a consistently negative delta across unrelated strains points at wort fermentability — mash temperature, grist, mash pH. A negative delta on one strain alone points at that library entry being wrong.

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}

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.