Skip to main content
Glama
flattery89

Brewfather MCP Server

by flattery89
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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:

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

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 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}

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:

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

Available Tools

9 tools
analyze_efficiencyA
Read-onlyIdempotent

Compute brewhouse efficiency across recent batches.

For each batch: potential points from the grain bill, measured OG points, and the measured volume, combined as (og_points * volume_gal) / potential_points.

Per-fermentable potential comes from Brewfather's stored potential field when present (the figure the app itself calculates with), falling back to 46 * yield/100.

Args: limit: How many recent completed/archived batches to consider. Default 15. grain_only: Skip batches containing extract, sugar or other non-mashed fermentables, which inflate the figure. Default True. volume_basis: "fermenter" (default, matches Brewfather's own Brew House Efficiency — volume into the fermenter, so kettle losses count against you) or "post_boil" (kettle volume at flameout, which reads higher by exactly the transfer loss).

Returns: Per batch: name, brew date, target vs measured OG, target vs measured volume, computed efficiency, and Brewfather's stored figure with the delta between them. Then aggregates: mean, median, standard deviation, overall and split by batch size.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
grain_onlyNo
volume_basisNofermenter

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, and the description adds valuable behavioral detail: the exact formula, fallback logic for missing potential, the impact of volume_basis on reading, and the grain_only filter. This disclosure goes well beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured: summary, formula, parameter explanations, and return values. Every section is purposeful and concise, with no redundancy or filler. The length is justified by the need to explain calculation nuances.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even with an output schema present, the description clearly lists the computed fields and aggregates, and explains all parameters and edge cases. It provides a complete picture for an AI agent to invoke the tool correctly and interpret results, making it fully contextual.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description explains every parameter in depth: limit, grain_only, and volume_basis with defaults and detailed implications. This fully compensates for the absent schema descriptions and adds meaning that the schema alone would not convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Compute brewhouse efficiency across recent batches' – a specific verb (compute) and resource (brewhouse efficiency) with clear scope. It distinguishes from sibling tools by focusing on aggregated efficiency analysis rather than listing or retrieving individual batches.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides clear context on when to use (analyzing efficiency across batches) and explains parameter semantics like volume_basis and grain_only. However, it does not explicitly name alternatives or state when not to use it, so it's a clear context but missing exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

check_connectionA
Read-onlyIdempotent

Verify credentials and report server configuration.

Makes one minimal API call. Never echoes credential values.

Returns: Connection status, the configured unit system and cache TTL, and cache hit statistics for this session.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as read-only and idempotent. The description adds non-redundant behavioral details: minimal API call, no credential echo, and the exact return items (status, unit system, cache TTL, cache hit statistics). This goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: three short sentences with a bullet list for return values. It is front-loaded with the purpose and every sentence earns its place, providing function, behavior, and output without fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with no parameters, and the description covers purpose, safety, and return values. The presence of an output schema and comprehensive annotations means the agent has everything needed. The description is complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, so schema coverage is 100% by default. The baseline for 0 params is 4, and the description appropriately omits parameter details. It does provide return-value context, but that is not part of parameter semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Verify credentials and report server configuration.' It is a specific verb+resource pair that distinguishes it from batch/recipe/inventory siblings. The added context about making one minimal API call and never echoing credentials reinforces its unique scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for credential verification and server configuration retrieval. 'Makes one minimal API call' signals low cost, and 'Never echoes credential values' reassures safety. However, it does not explicitly mention when not to use or name alternatives, but the sibling tools are unrelated enough that this is a minor gap.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

compare_batchesA
Read-onlyIdempotent

Line up 2-5 batches side by side on one dimension.

Rows are aligned by ingredient or step name, with an explicit null where a batch does not use that item — absence is usually the thing you are looking for when comparing versions of a recipe.

Args: batch_ids: Between 2 and 5 batch _id values. dimension: One of grain, hops, water, fermentation, measurements.

Returns: An aligned table: one row per ingredient or measurement, one column per batch, plus totals where a total is meaningful.

ParametersJSON Schema
NameRequiredDescriptionDefault
batch_idsYes
dimensionYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly and idempotent safety. The description adds valuable behavioral details: row alignment by ingredient/step name, explicit nulls for non-used items, and return of totals where meaningful. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-organized into purpose, args, and returns. The first sentence immediately states the function, and all information is directly useful with no padding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (2 parameters, no nested objects) and the availability of an output schema, the description is complete. It explains the alignment behavior, parameter ranges, and return format sufficiently for an agent to invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds essential constraints not present in the input schema: batch_ids must be between 2 and 5 values, and dimension provides an explicit enumeration (grain, hops, water, fermentation, measurements). This fully compensates for the 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('Line up'), resource ('2-5 batches'), and scope ('on one dimension'). It is easily distinguished from sibling tools like get_batch (single batch) and list_batches (listing).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for when to use the tool by describing the use case of comparing recipe versions and highlighting that 'absence is usually the thing you are looking for.' It does not explicitly name alternatives, but the purpose is unambiguous and the context signals suffice for correct selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_batchA
Read-onlyIdempotent

Fetch one batch in full, or just the sections you need.

Full batch records are large. Passing sections trims the payload to the parts you actually want.

Args: batch_id: The batch _id from list_batches. sections: Optional subset of: fermentables, hops, yeast, miscs, mash, fermentation, water, measurements, notes. Omit for everything.

Returns: Grain bill with weights and bill percentages, hop schedule with timing and use, yeast and pitch info, mash steps, fermentation schedule, water profile, and all measured values. Weights, volumes and temperatures carry both US customary and metric.

ParametersJSON Schema
NameRequiredDescriptionDefault
batch_idYes
sectionsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only/idempotent/non-destructive behavior. The description adds valuable context about large payloads and the ability to trim via sections, as well as the return structure including dual units.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is efficiently structured with a purpose statement, Args/Returns sections, and no wasted words. It front-loads the key information and includes necessary detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking an explicit alternative mention, the description is complete for a read-only fetch tool: it explains purpose, parameters, return content, and payload-size implications, with annotations covering safety.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description fully documents both parameters: batch_id as 'from list_batches' and sections with a complete list of valid values and the default behavior of returning everything when omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Fetch one batch in full, or just the sections you need,' using a specific verb and resource, and distinguishes from sibling tools by emphasizing full vs partial retrieval and payload trimming.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage is clear: use this to retrieve a specific batch with optional section filtering. However, it does not explicitly mention alternatives like get_batch_readings for measurements or list_batches for finding IDs, so it lacks explicit when-not or alternative guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_batch_readingsA
Read-onlyIdempotent

Fetch fermentation readings (Tilt or manual) for a batch.

An active ferment can log thousands of points, so the series is downsampled evenly rather than returned whole. The first and last readings are always kept.

Args: batch_id: The batch _id. latest_only: Return just the most recent reading. Default False. downsample_to: Approximate number of points to return. Default 200. Set to 0 to disable downsampling and return everything.

Returns: The reading series plus a derived summary: first and last gravity, min/max/mean temperature, apparent attenuation, and days elapsed. The summary is always computed over the full series, not the downsampled one.

ParametersJSON Schema
NameRequiredDescriptionDefault
batch_idYes
latest_onlyNo
downsample_toNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark readOnlyHint and idempotentHint, but the description adds crucial behavioral details: the series is downsampled evenly, first and last readings are always preserved, and the summary is computed over the full series even when downsampled. This goes well beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with a brief purpose, a concise behavioral note, and clearly labeled Args and Returns sections. It is appropriately sized for the tool's complexity, with every sentence contributing meaningful information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers downsampling semantics, parameter effects, and the full return summary fields. It is self-sufficient for an agent to correctly invoke the tool, even without an explicit output schema present.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description's Args section fully explains each parameter: batch_id as the batch _id, latest_only as returning the most recent reading, and downsample_to with the meaning of 0 (disable downsampling). This compensates completely for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Fetch fermentation readings (Tilt or manual) for a batch,' which uses a specific verb and resource, clearly distinguishing it from sibling tools like get_batch or list_recipes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

While the description does not name alternative tools, it provides clear context for when to use this tool (active ferment with thousands of points) and explains the downsampling trade-off. It lacks explicit exclusions or when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_recipeA
Read-onlyIdempotent

Fetch one recipe in full, or just the sections you need.

Args: recipe_id: The recipe _id from list_recipes. sections: Optional subset of: fermentables, hops, yeast, miscs, mash, fermentation, water, measurements, notes. Omit for everything.

Returns: The recipe with grain bill percentages, hop schedule, mash and fermentation steps, and target figures, in both unit systems.

ParametersJSON Schema
NameRequiredDescriptionDefault
sectionsNo
recipe_idYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only and idempotent hints, and the description adds useful behavioral context by detailing the return content (grain bill percentages, hop schedule, mash/fermentation steps, target figures, dual unit systems) and the effect of omitting sections. This goes beyond the annotations without contradicting them.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is tightly structured with Args and Returns sections, using only essential sentences. Every line adds value, from the purpose statement to parameter details and return summary.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With rich annotations and an output schema present, the description still provides complete context: it covers both parameters, return content, and section selection. No critical information is missing for a simple read-only fetch operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has zero descriptions, so the description fully compensates by clearly explaining recipe_id (source from list_recipes) and sections (allowed values and default behavior). This adds substantial meaning beyond the bare schema types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function with a specific verb ('Fetch') and resource ('one recipe'), and distinguishes it from siblings like list_recipes by focusing on fetching a single recipe with optional section filtering.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by noting recipe_id comes from list_recipes, but it does not explicitly state when to use this tool versus alternatives, nor does it provide exclusion criteria. The 'sections' parameter hints at selective fetching, but usage context is largely inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_batchesA
Read-onlyIdempotent

List brew batches, newest first by default.

Ordering is by brew date, not by id — Brewfather's default _id ordering is not chronological, so "newest" would otherwise be meaningless.

Args: status: Optional filter. One of Planning, Brewing, Fermenting, Conditioning, Completed, Archived. limit: Maximum batches to return. Default 25. newest_first: Sort by brew date descending. Default True.

Returns: Compact rows: id, batch number, name, style, brew date, status, and measured OG/FG/ABV. Use get_batch for the full record.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
statusNo
newest_firstNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare read-only, idempotent, non-destructive behavior. The description adds valuable behavioral nuances beyond these flags: it explains why ordering is by brew date (Brewfather's _id ordering is not chronological) and discloses the compact row format, directing to get_batch for full records.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an intro, ordering rationale, Args list, and Returns section. Each sentence earns its place, and the rationale for ordering is genuinely useful rather than filler. It is compact and easily scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers purpose, parameters, return values, and relationship to get_batch. With an output schema present, the compact row summary is sufficient. The tool is simple, and the description fully addresses all necessary aspects for selection and invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does excellently. Every parameter (status, limit, newest_first) is explained with its meaning, allowed values, and default behavior. The ordering nuance adds semantic depth to newest_first that the schema cannot convey.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The phrase 'List brew batches, newest first by default' explicitly names the action and resource. It distinguishes from sibling tools like list_recipes (recipes vs batches) and get_batch (compact vs full record), making the purpose unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description includes 'Use get_batch for the full record,' an explicit pointer to a sibling alternative. It also explains the ordering rationale, helping the agent understand when this list tool is appropriate. It doesn't exclude other sibling tools like list_recipes, but the resource type (brew batches) makes the context clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_inventoryA
Read-onlyIdempotent

List inventory for one ingredient category.

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

Args: category: One of fermentables, hops, miscs, yeasts. in_stock_only: Only items with a positive inventory amount. Default True.

Returns: Items with inventory amounts converted (fermentables in lb, hops and miscs in oz, yeast as pack counts), plus the relevant spec figures.

ParametersJSON Schema
NameRequiredDescriptionDefault
categoryYes
in_stock_onlyNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark the operation as read-only, idempotent, and non-destructive. The description adds concrete behavioral details: it returns only user-supplied inventory, converts units per ingredient type, and includes spec figures, which exceeds what annotations convey.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sections: purpose, args, returns. No fluff; every sentence carries operational meaning. The structure is conventional and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter list tool, the description covers execution constraints, input domain, and output format (units and spec figures). The existence of an output schema further reduces the need for return-type detail.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has no descriptions (0% coverage), so the description provides complete parameter semantics: category enumerates four valid values, and in_stock_only explains its filtering behavior and default. This fully compensates for the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear verb+resource: 'List inventory for one ingredient category.' It further clarifies scope by noting it excludes the full Brewfather database, distinguishing it from the sibling list_batches and list_recipes tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It states the tool is for listing user-added inventory only, with a caveat about not being the full database. However, it does not name an alternative tool for full database queries, so usage guidance is clear but not explicitly differentiated beyond sibling names.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_recipesA
Read-onlyIdempotent

List saved recipes.

Note: 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.

Args: limit: Maximum recipes to fetch before filtering. Default 25. name_contains: Case-insensitive substring filter applied client-side.

Returns: Compact rows: id, name, style, type, OG, FG, ABV, IBU, colour.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
name_containsNo

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the annotations (readOnlyHint, idempotentHint), the description discloses that there is no server-side name search, the filter is applied client-side, and it may return fewer results than limit. This is valuable behavioral context not covered by annotations. The return format is also specified.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a brief one-line purpose, a relevant note, and clear Args/Returns sections. Every sentence provides useful information without unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool, the description is complete. It covers parameters, return fields, and a critical behavioral caveat. The output schema existence and annotations further complete the picture, so no essential information is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides only titles and defaults, with no descriptions. The description's Args section fully explains both parameters: limit as 'Maximum recipes to fetch before filtering' and name_contains as 'Case-insensitive substring filter applied client-side.' This adds complete meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List saved recipes' with a specific verb and resource. It distinguishes from sibling tools by targeting recipes specifically, while the note about client-side filtering adds additional clarity about the tool's scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives like get_recipe or list_batches. The note about raising limit is a parameter usage tip, not a tool-selection guideline. There is no mention of when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 9 tool updatesv0.1.0
    • First observedanalyze_efficiency
    • First observedcheck_connection
    • First observedcompare_batches
    • First observedget_batch
    • First observedget_batch_readings
    • First observedget_recipe
    • First observedlist_batches
    • First observedlist_inventory
    • First observedlist_recipes
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.5/5.0

Scored across 9 tools

Disambiguation5/5

Each tool targets a distinct resource or operation: batches, recipes, readings, inventory, efficiency analysis, comparison, and connection check. There is no overlap in purpose, so an agent can easily select the right tool.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: list_*, get_*, analyze_*, compare_*, check_*. Even get_batch_readings fits the pattern with a compound noun, maintaining uniformity.

Tool Count5/5

Nine tools is well-scoped for a brewing data server. It covers core resources (batches, recipes, inventory) plus analysis and diagnostics without overloading the surface.

Completeness4/5

The tool set fully covers read-only access to batches, recipes, readings, inventory, and provides useful analytical features. The only gaps are write operations (create/update/delete) and a direct recipe search, but these are not essential for a read-focused integration.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mealie-mcp

    dvejsada
    A
    license
    Not graded
    quality
    B
    maintenance
    A read-only MCP server for Mealie that enables searching recipes, managing shopping lists, meal plans, and retrieving household/instance info via tools. Supports secure per-user authentication and multiple Mealie instances.
    MIT