Barkeeper

An MCP server that tracks a home bar: what's on the shelf, and the cocktail recipes you want to keep.

It is deliberately small — 7 tools, roughly 900 tokens of tool schema and instructions combined — so it stays cheap to run against local models.

Design

Inventory is presence-only. An item is either on the shelf or it isn't — there are no quantities or units to keep up to date. Each item carries a category so the listing can be grouped.

Recipes are a name, ingredient lines, and a method. Ingredients are plain text ("2 oz bourbon"), so there is no per-ingredient schema for a model to get wrong.

The model does the cross-referencing. There is no what_can_i_make tool. To answer that, the model calls list_inventory and list_recipes and compares the two — it already knows that a recipe calling for bourbon is satisfied by a bottle named "Buffalo Trace". The server's instructions tell it to match generously.

Tools

Tool	Arguments	Purpose
list_inventory	—	Everything on the shelf
add_item	name, category	Put one item on the shelf
remove_item	name	Take one item off
list_recipes	—	Every recipe with ingredients, without methods
get_recipe	name	One recipe in full
save_recipe	name, ingredients, instructions?	Save or replace a recipe
delete_recipe	name	Delete a recipe

list_recipes omits the method so the common "what can I make?" question stays cheap; get_recipe fills in the detail for the one drink you settle on.

Categories

list_inventory groups by category, in shelf order, skipping any that are empty:

spirit: Buffalo Trace bourbon, Tanqueray gin
liqueur: Campari
bitters: Angostura
mixer: Fever-Tree tonic water

Category	What belongs there
spirit	Base liquor — gin, vodka, whiskey, rum, tequila, brandy
liqueur	Sweetened or fortified — Campari, Cointreau, amaro, vermouth, sherry
wine	Still or sparkling — prosecco, Champagne
bitters	Cocktail bitters, dashed rather than poured — Angostura, Peychaud's
mixer	Non-alcoholic liquids — tonic, soda, juice, cola
syrup	Sweeteners — simple, orgeat, grenadine, honey
garnish	Citrus, herbs, olives, cherries
other	Anything else

Bitters gets its own category because it fits neither of the obvious two: it's alcoholic, so it isn't a mixer, but it's measured in dashes rather than poured, so grouping it with the spirits misrepresents the shelf.

The enum says spirit rather than liquor deliberately — liquor and liqueur differ by one letter, and asking a small model to choose between two near-identical strings invites silent miscategorisation.

Re-adding an item that's already on the shelf updates its category, so a wrong guess is corrected by just adding it again.

Names are matched case- and punctuation-insensitively, and partial names work when they're unambiguous — get_recipe("old fash") finds "Old Fashioned". An ambiguous partial returns an error listing the candidates rather than guessing.

Run it

The server speaks two transports. HTTP is the default in Docker: one port, plugged in by URL. stdio is the default for a local install, since that's how a client spawns it as a subprocess.

Docker (HTTP)

docker run -d --name barkeeper -p 8000:8000 -v barkeeper-data:/data \
  ghcr.io/nickmowen/mcp-barkeeper

Then point any MCP client at http://localhost:8000/mcp:

{
  "mcpServers": {
    "barkeeper": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Or with Claude Code:

claude mcp add --transport http barkeeper http://localhost:8000/mcp

Compose is included — docker compose up -d gives the same thing with the volume and port already wired.

The image runs as a non-root user (uid 1000), exposes 8000, and keeps its database in the /data volume. Prefer a named volume, as above: a bind mount to a host directory has to be writable by uid 1000 or the server can't create its database. A healthcheck confirms the port is bound.

Local (stdio)

uv sync

claude mcp add barkeeper -- uv --directory /path/to/mcp-barkeeper run barkeeper

Which HTTP transport?

--transport http serves Streamable HTTP at /mcp — the current MCP transport, which POSTs requests and streams replies back over SSE. This is what you want.

--transport sse serves the older HTTP+SSE transport, a separate /sse stream plus a /messages/ endpoint. It was deprecated in MCP 2025-03-26 and is here only for clients that haven't moved yet.

Configuration

Flags beat environment variables, which beat defaults.

Variable	Flag	Default	Purpose
BARKEEPER_TRANSPORT	--transport	stdio (http in Docker)	stdio, http, or sse
BARKEEPER_HOST	--host	127.0.0.1 (0.0.0.0 in Docker)	Interface to bind
BARKEEPER_PORT	--port	8000	Port to bind
BARKEEPER_DB_PATH	—	platform data dir	SQLite file; :memory: for throwaway
BARKEEPER_ALLOWED_HOSTS	—	unset	Comma-separated; enables DNS-rebinding protection
BARKEEPER_ALLOWED_ORIGINS	—	unset	Comma-separated; enables DNS-rebinding protection

Binding to 0.0.0.0 puts the server on every interface the container can reach, with no authentication — keep it on a private network or bound to 127.0.0.1. Setting either allow-list switches on DNS-rebinding protection, which rejects requests whose Host or Origin header isn't named:

BARKEEPER_ALLOWED_HOSTS="localhost:*,127.0.0.1:*"

Both are left unset by default because enabling protection with an empty allow-list rejects every request.

Storage

A single SQLite file. In Docker it lives at /data/barkeeper.db; locally it is created on first use at:

• macOS: ~/Library/Application Support/barkeeper/barkeeper.db
• Linux: ~/.local/share/barkeeper/barkeeper.db
• Windows: %APPDATA%\barkeeper\barkeeper.db

Override with BARKEEPER_DB_PATH. Use :memory: for a throwaway session.

Development

uv run pytest

create_server(conn) accepts a connection, so tests run against an in-memory database with no global state.