brewers-almanack

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

MIT