Skip to main content

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. Add batches.write / recipes.write / inventory.write to enable update_batch / create_recipe and update_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 by mcp); pinned via the committed uv.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)

Source distribution for mcp-server-brewfather 0.2.0
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)

Table of built distributions (wheels) for mcp-server-brewfather 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page