io.github.gregario/brewers-almanack

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 mcp add brewers-almanack -- npx -y brewers-almanack

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"]
    }
  }
}

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "brewers-almanack": {
      "command": "npx",
      "args": ["-y", "brewers-almanack"]
    }
  }
}

Add to .vscode/mcp.json:

{
  "servers": {
    "brewers-almanack": {
      "command": "npx",
      "args": ["-y", "brewers-almanack"]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "brewers-almanack": {
      "command": "npx",
      "args": ["-y", "brewers-almanack"]
    }
  }
}

Add to settings.json:

{
  "context_servers": {
    "brewers-almanack": {
      "command": {
        "path": "npx",
        "args": ["-y", "brewers-almanack"]
      }
    }
  }
}

Tools

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

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