Brewfather MCP

Read the English document

This is a Model Context Protocol service that runs on your personal computer. It can read, search, create, and safely modify Brewfather recipes through the Brewfather API v2 and the Brewfather 3.1 public beta interface.

The service communicates over local standard input/output. Brewfather credentials are stored only on the user's own computer; a short-lived preview confirmation token is required before creating or modifying recipes. This service intentionally does not provide recipe deletion.

Easiest installation: let an AI assistant do it for you (recommended)

This tool is mainly for homebrewers who are not familiar with terminal commands. You can have an AI assistant that can access the local terminal and supports the Model Context Protocol do the installation, such as Codex, Claude Code, Cursor, the assistant in Visual Studio Code, or the Gemini command-line tool.

Start a new conversation and paste the following text to the agent:

请帮我安装当前项目中的 brewfather-mcp，并注册到我正在使用的agent。

请你：
1. 检查本机是否有 Node.js 20 或更高版本；
2. 在当前项目目录安装依赖、构建项目并安装 brewfather-mcp 命令；
3. 自动识别我正在使用的智能助手，运行对应的 brewfather-mcp install 命令；
4. 如果打开本机授权页面，让我自己在页面中输入 Brewfather 用户编号和应用程序接口密钥。不要让我把密钥发到对话里，也不要输出或读取密钥内容；
5. 等我提交授权页面后，运行 brewfather-mcp doctor，并检查模型上下文协议服务是否已成功注册。

请直接开始执行；只有在必须由我操作授权页面时再提醒我。

3. The AI assistant will open an authorization page accessible only from this machine. Enter your Brewfather API ID and API key on the page, then submit.

4. After installation succeeds, restart the AI assistant or start a new conversation, then simply say:

使用 Brewfather 工具列出我最近的 5 个配方。

Web-only AI assistants usually cannot install a local service that runs on your computer. Please use a desktop, IDE, or command-line assistant that can access local projects and the terminal.

Related MCP server: Tandoor MCP Server

Requirements

• Node.js 20 or later

• Brewfather Premium or an active Premium trial

• Joining the Brewfather 3.1 public beta is required to create or modify recipes

• A Brewfather API key with recipes.read permission; writing recipes also requires recipes.write permission

Install from source

cd /path/to/brewfather-mcp
npm install
npm run build
npm link

Open the local credentials page and register the service with the chosen AI assistant:

brewfather-mcp install codex

The setup page only listens on a random port on 127.0.0.1. It validates the credentials with a read-only request, saves them locally, and then exits automatically. Generate the key in Brewfather under Settings → API. There is no need to grant recipes.delete permission; this service never uses it.

Where credentials are stored

Credentials are stored as JSON in the operating system's user configuration directory:

A different path can be specified with BREWFATHER_MCP_CONFIG. On Unix-like systems, the configuration directory is set to 0700 and the configuration file to 0600. The file contains plaintext credentials; do not sync, share, or commit it to a repository. Container and CI environments can use the BREWFATHER_USER_ID and BREWFATHER_API_KEY environment variables instead.

Common commands:

brewfather-mcp setup
brewfather-mcp doctor
brewfather-mcp config path
brewfather-mcp auth logout

Install into different AI assistants

The installer supports the following AI assistants:

brewfather-mcp install codex
brewfather-mcp install claude
brewfather-mcp install cursor
brewfather-mcp install vscode
brewfather-mcp install gemini
brewfather-mcp install all
brewfather-mcp install generic

The installer tries to use each assistant's official command-line tool:

• Codex: codex mcp add

• Claude Code: claude mcp add --scope user

• Cursor: agent mcp add

• Visual Studio Code: code --add-mcp

• Gemini: gemini mcp add --scope user

generic outputs a standard mcpServers JSON configuration for other compatible clients. The registration command uses the absolute paths of the current Node.js executable and this software's compiled entry point, so Brewfather credentials never appear in the assistant's configuration.

Use in a new conversation

Start a new AI assistant conversation and say:

使用 Brewfather 工具列出我最近的 5 个配方，只读取，不要修改。

To modify a recipe, you can say:

使用 Brewfather 工具找到“West Coast IPA”，把其中的 Citra 干投增加 20 克。先显示修改预览，等我明确确认后再写入。

Available tools

• brewfather_connection_status

• brewfather_list_recipes

• brewfather_search_recipes

• brewfather_get_recipe

• brewfather_preview_recipe_create

• brewfather_apply_recipe_create

• brewfather_preview_recipe_update

• brewfather_apply_recipe_update

To prevent Brewfather from rejecting or silently altering data on write, the following checks are performed when generating a preview:

• Brewfather's write API does not accept string tags. Omit tags unless you copy the complete tag object from an existing recipe.

• Additive units are limited to g, mg, kg, ml, l, tsp, tbsp, pkg, items, or drops. Common aliases such as tablet and dose are automatically converted to items.

• When a malt has only a Lovibond color and no color, the tool automatically calculates EBC to prevent Brewfather from saving the color as 0.

• All automatic conversions are listed in the preview's normalizations and should be confirmed by the user along with any other changes.

Confirmation tokens for creating and modifying recipes expire after ten minutes and can only be used once. Before modifying a recipe, the service reads the recipe again; if the recipe changed after the preview was generated, the write is rejected.

Nested objects in the modification parameters are deep-merged locally. Because Brewfather's recipe partial-update API only shallow-merges top-level fields, arrays are replaced entirely. Read the current recipe before modifying, and pass the complete fermentables, hops, yeasts, or miscs array.

Brewfather values consistently use metric units: liters, kilograms, grams, degrees Celsius, and specific gravity.

Development

npm run typecheck
npm test
npm run build

After building, you can run the Model Context Protocol inspector:

npx @modelcontextprotocol/inspector node dist/cli.js serve

Protocol communication uses standard output. Runtime diagnostics are written only to standard error; authorization headers and API keys are never logged.

API notes

• The REST API path version is still /v2; recipe writing is part of the Brewfather 3.1 public beta.

• The API uses HTTP basic authentication with the Brewfather user ID as the username.

• Brewfather currently limits each key to 500 calls per hour.

• This service does not provide recipe version creation, locking, restoration, rollback, or deletion.

See the Brewfather API documentation and the version 3.1 public beta notes.