Shaky

Your local AI bartender. Shaky is an MCP server that knows exactly what is in your home bar: spirits, liqueurs, syrups, juices, fruit, garnishes, equipment and glasses. Your AI (Claude Desktop, for example) already knows thousands of recipes. Shaky gives it the missing piece, a reliable picture of what you actually have, so it can suggest drinks you can make right now, offer substitutes, help you use up the open Lillet before it turns, and keep your shopping list.

Next to the MCP server runs a playful web UI on localhost, where you see and manage your bar yourself. You and the AI write to the same database, and changes show up on both sides instantly.

Local only, no authentication. Shaky binds to 127.0.0.1 and is meant to run on your own computer.

For adults of legal drinking age. Please drink responsibly.

Features

• Bar inventory that stays true: fill levels (full, three quarters, half, quarter, almost empty, empty) or exact ml, bottle counts, opened date and shelf life with sensible editable defaults per category (an open vermouth or Lillet keeps about five weeks in the fridge, fresh juice a few days, spirits practically forever).

• Fuzzy recipe matching: "rum" matches any rum, "dark rum" never matches your white rum. Empty and expired bottles do not count. Find what you can make now and what misses just one ingredient.

• Log a drink, deduct the stock: exact for bottles with ml, estimated from the fill level otherwise, limes via juice per piece. When a bottle runs out and you have a spare, the next one is opened.

• Data driven: equipment (including substitutes like "a jam jar can replace a shaker"), glasses, storage locations and category defaults are data the AI can change through tools. No code changes needed.

• Live web UI: your bar as a scene (shelf, fridge, freezer, pantry), recipes with what is in stock, a "Mixed it!" button, shopping list, equipment and history. When the AI changes something, a speech bubble tells you ("Shaky set Lillet Blanc to a quarter"). English and German, light and dark mode.

• Every change is logged with its source (you in the web UI, or the AI over MCP).

Related MCP server: scraps-kitchen-mcp

Requirements

• Node.js 22.12 or newer (24 LTS recommended)

• Windows, macOS or Linux. No database server, no Docker, no C++ compiler. SQLite ships with the package as a prebuilt binary for all three systems (the repo's .npmrc turns off install scripts so npm never tries to compile it).

Installation

git clone https://github.com/akquisio-dev/Shaky-mcp.git
cd Shaky-mcp
npm install
npm run build
npm run seed      # optional: loads an example bar and twelve recipes
npm run doctor    # checks the setup and prints your Claude Desktop config

Your data lives outside the repository in a per-user folder (override with SHAKY_DATA_DIR):

Running

There are two ways to start Shaky. Both use the same database, so you can mix them.

Settings (environment variable or flag):

Claude Desktop

The easiest way is npm run doctor: it prints the exact snippet with the absolute paths for your machine. Open the config file (Claude Desktop: Settings, Developer, Edit Config), merge the shaky entry into mcpServers and restart Claude Desktop.

Using the absolute path of node avoids PATH problems with apps started from the dock or start menu (which node on macOS/Linux, where node on Windows).

macOS (~/Library/Application Support/Claude/claude_desktop_config.json)

{
  "mcpServers": {
    "shaky": {
      "command": "/usr/local/bin/node",
      "args": ["/Users/you/Shaky-mcp/dist/cli.js", "mcp"]
    }
  }
}

Windows (%APPDATA%\Claude\claude_desktop_config.json, note the doubled backslashes)

{
  "mcpServers": {
    "shaky": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\Users\\you\\Shaky-mcp\\dist\\cli.js", "mcp"]
    }
  }
}

Linux (~/.config/Claude/claude_desktop_config.json, for community builds of Claude Desktop or any other MCP client)

{
  "mcpServers": {
    "shaky": {
      "command": "/usr/bin/node",
      "args": ["/home/you/Shaky-mcp/dist/cli.js", "mcp"]
    }
  }
}

Then ask Claude something like "What can I mix tonight, something fruity?" or "I just finished the Lillet." Clients that speak Streamable HTTP can use http://localhost:8787/mcp while shaky serve runs.

MCP interface

Tools: get_bar_overview (call first), list_ingredients, get_ingredient, add_ingredient, update_ingredient, archive_ingredient, set_fill_level, mark_opened, get_expiring, list_equipment, set_equipment, list_glassware, set_glassware, set_location, set_category_defaults, list_recipes, get_recipe, save_recipe, delete_recipe, find_makeable_recipes, log_mix, shopping_list_get, shopping_list_add, shopping_list_update, get_recent_activity.

Resources: shaky://bar/overview, shaky://inventory, shaky://equipment.

Prompts: suggest_drink (mood, taste), use_up_leftovers.

Every tool answers with a short readable line plus compact JSON. Tools that change something list exactly what changed.

Security

Shaky has no authentication in this version. That is fine on your own computer because it only listens on 127.0.0.1 and only answers requests whose Host and Origin point to localhost (this blocks DNS rebinding and other websites in your browser writing to your bar). Do not bind it to a public interface. To use it on a remote machine, tunnel it over SSH, see docs/development.md.

Tech choices

• Node.js + TypeScript (ESM) and the official MCP TypeScript SDK with zod schemas shared by MCP tools, REST API and web client.

• SQLite via better-sqlite3: stable, synchronous (simple transactions), and since v13 the package ships prebuilt binaries for Windows, macOS and Linux (x64 and arm64), so npm install needs no compiler. The built-in node:sqlite is not yet marked stable in Node 22/24. WAL mode lets the stdio process and the web server share the file; migrations are versioned and checksummed.

• Hono for the HTTP server: small, built-in Server-Sent Events, and the MCP SDK's web-standard transport plugs straight into a route.

• Vite + plain TypeScript for the UI, no framework. Views are plain DOM, so a 2D game engine (PixiJS or similar) can later draw into its own canvas next to them, sharing the same store and event stream.

• Vitest, ESLint, Prettier, GitHub Actions on Ubuntu, Windows and macOS.

Roadmap

• Stage 2, the mixing game (free mode): the bar view becomes a game scene. Drag bottles from shelf, fridge and freezer, hold to pour with a cl counter, shake with a shake meter, blend, muddle, and watch the glass fill in layers of the real ingredient colors. Only what you own appears, with an optional "sandbox: everything available" switch.

• Stage 3, training with the AI: the AI loads an exercise into the game (start_training with a recipe), the game checks order and amounts against the recipe steps and scores you, and the AI reads the result and gives feedback. Plus a "mix for real" step-by-step kitchen view that deducts stock at the end.

Already prepared: structured recipe steps, a color per ingredient, storage locations as scene zones, equipment as data and a server-to-browser event stream that game events can share.

Contributing

See CONTRIBUTING.md and docs/development.md.

License

MIT © akquisio-dev