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.

Related MCP server: Mealie MCP Server

Tools

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

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.

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.