About brewers-almanack
brewers-almanack is an MCP server that gives AI assistants structured brewing reference data and guidance. It covers styles, ingredients, off-flavour diagnosis, water profiles, recipes, and food pairings, with data embedded locally.
Key features
- 01Search 85 BJCP beer styles
- 02Search hops, malts, yeasts, and adjuncts
- 03Diagnose off-flavours and prevention steps
- 04Match water profiles to cities or styles
- 05Generate recipes for target styles
- 06Suggest beer and food pairings
Use cases
- 01Identify causes of a buttery or other off-flavour
- 02Find ingredients suited to a beer style
- 03Draft a recipe with grain, hops, yeast, and water
- 04Choose food pairings for a beer
MCP support
Exposes six brewing-focused tools to MCP clients for style and ingredient search, diagnosis, water matching, recipe suggestions, and pairing guidance. Brewing datasets are embedded, with no API keys or network dependencies.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
6Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| query | string | Yes | Style name, category, or characteristic to search for |
Details
From the project README
Brewers Almanack
A brewing knowledge MCP server: beer styles, ingredients, off-flavour diagnosis, water chemistry, and recipe guidance for AI assistants.
Ask your AI assistant about beer styles, diagnose off-flavours, build recipes, match water profiles, and pair food (all backed by real brewing data, not hallucinations).
6 tools. Zero config. Works with every MCP-compatible IDE.
Install
npx -y brewers-almanack
No API keys, no network dependencies. All brewing data is embedded.
Add to your IDE
Claude Code
claude mcp add brewers-almanack -- npx -y brewers-almanack
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):
{
"mcpServers": {
"brewers-almanack": {
"command": "npx",
"args": ["-y", "brewers-almanack"]
}
}
}
Cursor
Add to .cursor/mcp.json:
{
"mcpServers": {
"brewers-almanack": {
"command": "npx",
"args": ["-y", "brewers-almanack"]
}
}
}
VS Code (Copilot)
Add to .vscode/mcp.json:
{
"servers": {
"brewers-almanack": {
"command": "npx",
"args": ["-y", "brewers-almanack"]
}
}
}
Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"brewers-almanack": {
"command": "npx",
"args": ["-y", "brewers-almanack"]
}
}
}
Zed
Add to settings.json:
{
"context_servers": {
"brewers-almanack": {
"command": {
"path": "npx",
"args": ["-y", "brewers-almanack"]
}
}
}
}
Tools
| Tool | Description |
|---|---|
search_styles | Search 85 BJCP beer styles by name, category, or characteristics. Returns vital statistics, overall impression, ingredients, and commercial examples. |
search_ingredients | Search hops, malts, yeasts, and adjuncts by name, type, or characteristic. Filter by category or search across all. |
diagnose_off_flavour | Identify off-flavours from taste or aroma descriptions. Returns the likely compound, causes, prevention steps, and styles where it may be acceptable. |
match_water_profile | Find brewing water profiles by city name or beer style. Returns mineral composition (Ca, Mg, Na, Cl, SO4, HCO3) and style recommendations. |
suggest_recipe | Generate a recipe for a target beer style. Returns grain bill, hop schedule, yeast selection, water profile, and process parameters. |
pairing_guide | Beer and food pairing suggestions. Search by beer style or dish name. Returns matches with complement, contrast, and cleanse principles. |
Example Conversations
"What hops work in a Belgian Dubbel?"
Searches ingredients for hops that complement Belgian styles, returning varieties like Styrian Goldings and Saaz with alpha acid ranges, aromas, and substitutes.
"My beer tastes like butter, what went wrong?"
Diagnoses diacetyl: identifies the compound, explains causes (incomplete fermentation, premature racking), and gives prevention steps (diacetyl rest, healthy yeast pitch).
"Suggest a recipe for a West Coast IPA"
Builds a complete recipe: pale malt base with crystal malt, Centennial/Cascade hop schedule with dry hop additions, American ale yeast, and a Burton-style water profile.
"What food pairs well with a stout?"
Returns pairing suggestions (oysters, chocolate desserts, grilled meats) with principles explaining why each pairing works (complement, contrast, or cleanse).
Data Sources
| Dataset | Records | Source | Licence / Basis |
|---|---|---|---|
| Beer styles | 85 | BJCP 2021 Guidelines via beerjson/bjcp-json | MIT; BJCP attribution |
| Hops | 113 | kasperg3/HopDatabase | MIT |
| Malts | 38 | Compiled from published maltster spec sheets | Factual data |
| Yeasts | 33 | Compiled from published yeast lab spec sheets | Factual data |
| Adjuncts | 21 | Compiled from brewing literature | Factual data |
| Water profiles | 20 | Compiled from brewing literature | Factual data |
| Off-flavours | 25 | Compiled from brewing science literature | Factual data |
| Food pairings | 23 | Compiled from Cicerone curriculum and pairing guides | Factual data |
Roadmap
See ROADMAP.md for planned features: brewing calculators, recipe intelligence, BeerXML/BeerJSON integration, and a brewing journal.
Contributing
Contributions are welcome, especially data contributions. More hop varieties, yeast strains, regional water profiles, and food pairings make the server more useful for everyone.
git clone https://github.com/gregario/brewers-almanack.git
cd brewers-almanack
npm install
npm run build
npm test # 73 tests
Running locally
claude mcp add brewers-almanack-dev -- node /path/to/brewers-almanack/dist/index.js
See ROADMAP.md for areas where contributions are most needed.
Licence
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.