io.github.gregario/brewers-almanack
Brewing knowledge MCP — beer styles, ingredients, off-flavours, water chemistry, recipes
Install
Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).
brewers-almanackclaude mcp add brewers-almanack -- npx -y brewers-almanack@0.1.0{
"mcpServers": {
"brewers-almanack": {
"command": "npx",
"args": [
"-y",
"brewers-almanack@0.1.0"
]
}
}
}Documentation
From the project's README on GitHub, refreshed weekly. Links open on GitHub.
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-almanackNo API keys, no network dependencies. All brewing data is embedded.
Add to your IDE
Claude Code
claude mcp add brewers-almanack -- npx -y brewers-almanackClaude 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 testsRunning locally
claude mcp add brewers-almanack-dev -- node /path/to/brewers-almanack/dist/index.jsSee ROADMAP.md for areas where contributions are most needed.
Licence
Frequently asked questions
What is io.github.gregario/brewers-almanack?
Brewing knowledge MCP — beer styles, ingredients, off-flavours, water chemistry, recipes
How do I install io.github.gregario/brewers-almanack?
It runs on your machine. In Claude Code: claude mcp add brewers-almanack -- npx -y brewers-almanack@0.1.0. For other clients, paste the JSON configuration from this page into their MCP settings.
Does io.github.gregario/brewers-almanack need an API key?
Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.
Is io.github.gregario/brewers-almanack open source?
Yes. Its code is on GitHub under the MIT license.
Who maintains io.github.gregario/brewers-almanack?
It is published by gregario. AI.tn lists it but does not maintain or endorse it.
From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.