mcp-server-brewfather
An MCP server for the Brewfather API. It lets an LLM read your batches, recipes, fermentation readings, and inventory, and make the routine writes that come up while brewing: advancing a batch's status, logging measured gravities and volumes, tweaking a recipe, and adjusting stock after brew day.
Brewfather has no official MCP server; this wraps the public v2 API directly.
Tools
| Tool | What it does |
|---|---|
find_batches(name?, status?) |
Find batches by name substring and/or status → {id, name, batch_no, status, brewer, brew_date, recipe} |
get_batch(batch_id) |
Batch summary, measured values, notes and log entries, scheduled events (brew day, dry hop, bottling, …), and embedded recipe (stats + ingredient bill) |
get_readings(batch_id, limit?) |
Most recent hydrometer/sensor readings, oldest→newest (limit=0 for all) |
get_brewtracker(batch_id) |
Brew-day tracker: current stage and step, seconds left on the stage timer, upcoming steps, next stage |
update_batch(batch_id, status?, measurements?) |
Set status and/or measured* values (validated before sending) |
find_recipes(name?) |
Find recipes by name substring → {id, name, author, type, style, equipment} |
get_recipe(recipe_id) |
Target stats (OG, FG, ABV, IBU, color, …) and ingredient bill |
create_recipe(name, type?, fields?, ingredients?) |
New All Grain or Extract recipe with settings and an ingredient bill |
update_recipe(recipe_id, fields?, ingredients?) |
Change settings (batch size, boil time, efficiency, …) and add/change/remove ingredients |
list_inventory(kind, name?, in_stock_only?) |
Fermentables, hops, miscs, or yeasts in stock |
set_inventory(kind, item_id, amount? | adjust?) |
Set absolute stock, or add/subtract |
All values are metric (SG, liters, kg/g, °C) — the API accepts nothing else. Timestamps are returned as ISO-8601 UTC.
Brewfather computes recipe stats (OG, FG, ABV, IBU, color) in the app, not the API.
After create_recipe or update_recipe, the app shows correct stats as soon as you
open the recipe, but get_recipe returns the stored values, which the API never
calculates (a new recipe has none).
Stats can't be written through this server.
Batch notes and log entries are read-only: get_batch returns them, but the API
ignores any attempt to write them, so add notes in the Brewfather app.
Setup
1. Generate an API key
In Brewfather: Settings → API → Generate API Key. Pick scopes to match what you want the server to do (see Security posture). Note the User ID shown alongside the key.
2. Install
Requires Python 3.12+. With uv, there is nothing
to install: uvx fetches and runs the published package. Otherwise:
pip install mcp-server-brewfather
# or, isolated:
pipx install mcp-server-brewfather
Register with Claude
Claude Code:
claude mcp add brewfather --scope user \
-e BREWFATHER_USER_ID=your_user_id -e BREWFATHER_API_KEY=your_api_key \
-- uvx mcp-server-brewfather
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"brewfather": {
"command": "uvx",
"args": ["mcp-server-brewfather"],
"env": {
"BREWFATHER_USER_ID": "your_user_id",
"BREWFATHER_API_KEY": "your_api_key"
}
}
}
}
Security posture
- The API key's scopes are the trust boundary. For read-only use, grant only
batches.read,recipes.read,inventory.read. Addbatches.write/recipes.write/inventory.writeto enableupdate_batch/create_recipeandupdate_recipe/set_inventory. Never grant*.delete— no tool uses it. - No delete tools. Every write is checked against an allowlist of fields before it's sent, because the API silently accepts unknown fields.
- Two dependencies only (
mcp,httpx— the latter already required bymcp); pinned via the committeduv.lock. - Credentials live in a gitignored
.env/ Claude config.
Rate limits
Brewfather allows 500 calls per hour per API key. List tools page 50 items per
call, so find_*/list_inventory cost one call per 50 items. A rate-limited call
surfaces as an error naming the Retry-After delay.
Development
cp .env.example .env # then fill in your user id / API key
source .env
uv sync # install deps (incl. dev group)
uv run ruff check . # lint
uv run ruff format . # format
uv run pytest # unit tests (acceptance auto-skipped)
uv run pytest --run-acceptance # + live read-only API checks (needs BREWFATHER_* creds)
CI (GitHub Actions) runs the PR-title check, ruff lint/format, and the unit tests
on every PR; the CI Success job is the aggregate gate. Acceptance tests are not
run in CI — they need live credentials and stay local/manual. They are read-only
and never modify your brewing data.
Releases are automated: release-please keeps a release PR open from the
conventional commits on main, and merging it tags vX.Y.Z, which triggers
release.yml to publish to PyPI via trusted publishing.
License
MIT — see LICENSE.
Metadata
Release files for mcp-server-brewfather 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcp_server_brewfather-0.2.0.tar.gz | 69.1 kB | With provenance | Details for mcp_server_brewfather-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcp_server_brewfather-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for mcp_server_brewfather-0.2.0-py3-none-any.whl |
Total release size: 85.1 kB
Release files / mcp_server_brewfather-0.2.0.tar.gz
| Download URL | mcp_server_brewfather-0.2.0.tar.gz |
|---|---|
| Size | 69.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8131c373ba626a96f5d5f9b40167afeec2fbdc8e07bcdc20cedf960a3aba6410
|
|
BLAKE2b-256 checksum How to use checksums |
3b293cd3ea71ea16de45445bf6686f0ed468ff1e9deedc750a0ef1a1ee633f05
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logRelease files / mcp_server_brewfather-0.2.0-py3-none-any.whl
| Download URL | mcp_server_brewfather-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e8c1498e56f98eb1998aff8d51456491f89cedc2132ae6b5f7a2ed1bf63fe4c1
|
|
BLAKE2b-256 checksum How to use checksums |
6300546465b4940590b3e7c52f1934cab5d04203be7a64acb8aa1248914923e5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logSecurity for mcp-server-brewfather 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mcp_server_brewfather-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.