# 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](#read-only-guarantee) below.

---

## Setup

### 1. Requirements

- A **Brewfather Premium** subscription — API access requires it.
- [**uv**](https://docs.astral.sh/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

```bash
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

```bash
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`):

```json
{
  "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:

```bash
uv run python scripts/smoke.py
```

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

```bash
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 |
| `analyze_attenuation` | `limit` (20), `group_by` (yeast\|style\|none), `include_incomplete` (false) | Per-batch apparent attenuation with strain, library figure, delta, and the mash rest temperature; aggregates per strain with a `suggested_library_value` |
| `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.

**`analyze_attenuation`** — see [Attenuation](#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:

```json
{"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.

---

## 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`:

| `fg_source` | Field | Trust |
|---|---|---|
| `measured` | `measuredFg` | A real measurement. The only source used by default. |
| `reading` | Terminal gravity inferred from the fermentation series | Only with `include_incomplete=True`, and always flagged. |
| *(never used)* | Brewfather's `measuredAttenuation` | Reported for context only — see below. |

**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:

```json
{"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](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.