gregario/brewers-almanack
📇 🏠 - A brewing knowledge MCP server with beer styles (BJCP 2021), 113 hop varieties, malts, yeasts, water profiles, off-flavour diagnosis, recipe suggestions, and food pairings.
Quick Install
{
"mcpServers": {
"gregario-brewers-almanack": {
"command": "npx",
"args": [
"-y",
"gregario-brewers-almanack"
]
}
}
}Using an AI coding agent (Claude Code, Cursor, etc.)? Copy a ready-made prompt that tells it to fetch the setup instructions and install this server for you.
Documentation Overview
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.