Cellarbrain

AI sommelier for your wine cellar. Transforms Vinocell CSV exports into normalised Parquet tables, per-wine Markdown dossiers, and an in-process DuckDB query layer that AI agents can use via the Model Context Protocol.

Quick start

# Clone and install (Python 3.11+)
git clone https://github.com/urban-buss/cellarbrain.git
cd cellarbrain
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -e .

Usage

1. Run the ETL pipeline

Export your cellar from cellarbrain (File → Export → CSV) and place the files in raw/:

raw/
├── export-wines.csv
├── export-bottles-stored.csv
└── export-bottles-gone.csv      # optional

Then run:

# Full load (first time)
cellarbrain etl raw/export-wines.csv raw/export-bottles-stored.csv raw/export-bottles-gone.csv -o output

# Incremental sync (subsequent runs — detects changes, preserves IDs)
cellarbrain etl raw/export-wines.csv raw/export-bottles-stored.csv raw/export-bottles-gone.csv -o output --sync

Output goes to output/ — 12 Parquet entity files and per-wine Markdown dossiers under output/wines/.

2. Query your cellar

# SQL query (DuckDB syntax)
cellarbrain query "SELECT w.name, wy.name AS winery, w.vintage FROM wine w JOIN winery wy ON w.winery_id = wy.winery_id LIMIT 10"

# Output as CSV or JSON
cellarbrain query "SELECT * FROM wine LIMIT 5" --format csv
cellarbrain query "SELECT * FROM bottle WHERE status = 'stored'" --format json

# SQL from a file
cellarbrain query -f my_query.sql

3. Cellar statistics

cellarbrain stats                     # Overall summary
cellarbrain stats --by country        # Grouped by country
cellarbrain stats --by grape          # Grouped by grape variety
# Also: region, category, vintage, winery, cellar, provider, status

4. Wine dossiers

cellarbrain dossier 42                # Read dossier for wine #42
cellarbrain dossier --search Barolo   # Search wines by name, grape, region…
cellarbrain dossier --pending         # Wines with pending agent research

5. Validate output

cellarbrain validate                  # Check Parquet integrity

6. Start the MCP server

cellarbrain mcp                       # stdio transport (default)
cellarbrain mcp --transport sse       # SSE transport for HTTP clients

All subcommands accept -d <path> to point at a different data directory (default: output).

Legacy mode: The old cellarbrain <wines.csv> <bottles.csv> syntax still works but emits a deprecation warning.

Web Explorer

A local web dashboard for browsing your cellar, observability data, and running queries interactively.

cellarbrain dashboard          # opens at http://localhost:8017

Pages: overview, tool usage, errors, sessions, latency charts, live tail (SSE), cellar browser, bottles, drinking window, tracked wines, SQL playground, statistics, and workbench. Requires a prior ETL run and MCP log store.

MCP server

The MCP server exposes 7 read/write tools for AI agents (Claude, OpenClaw, Copilot, etc.). Tools are thin data primitives — all reasoning stays in the agent.

Tools

Resources

Prompts

Configure with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "cellarbrain": {
      "command": "cellarbrain",
      "args": ["mcp"],
      "env": {}
    }
  }
}

If cellarbrain is installed in a virtualenv, use the full path:

{
  "mcpServers": {
    "cellarbrain": {
      "command": "/path/to/cellarbrain/.venv/bin/cellarbrain",
      "args": ["mcp"],
      "env": {}
    }
  }
}

To point at a different data directory:

{
  "mcpServers": {
    "cellarbrain": {
      "command": "cellarbrain",
      "args": ["-d", "/path/to/output", "mcp"],
      "env": {}
    }
  }
}

Configure with VS Code (Copilot)

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "cellarbrain": {
      "command": "cellarbrain",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Or with a virtualenv on Windows:

{
  "servers": {
    "cellarbrain": {
      "command": ".venv\\Scripts\\cellarbrain.exe",
      "args": ["-d", "output", "mcp"],
      "env": {}
    }
  }
}

Configure with OpenClaw

See .docs/design/openclaw-skill.md for the full skill integration design.

Optional OpenClaw iMessage notifications

Cellarbrain can ask OpenClaw to send a short iMessage after each successful ETL, including runs with no detected changes. When notifications are enabled, failed ETL runs also send a best-effort failure alert. Notifications are disabled by default.

Add this to your local cellarbrain.toml (keep personal recipient details out of shared config files):

[notifications]
enabled = true
target = "+417XXXXXXXX" # replace with your iMessage number in international format
# command = "openclaw"            # or an absolute path if launchd cannot find it
# timeout_seconds = 15
# strict = false                  # success-alert delivery failure does not fail ETL

The recipient is passed to OpenClaw's documented openclaw message send --channel imessage command. OpenClaw and its iMessage channel must already be configured on the local Mac. Cellarbrain uses a shell-free subprocess call and does not expose the Gateway. Successful sends are recorded in .cellarbrain-notifications.json inside the ETL output directory to suppress duplicate sends for the same run. Failure messages contain no exception text or source data.

Data model

The ETL produces 12 normalised Parquet tables:

Plus per-wine Markdown dossiers in output/wines/ with:

• ETL-owned sections (identity, origin, inventory, tastings, etc.)
• Agent-owned sections (producer profile, vintage report, food pairings, etc.)
• YAML frontmatter tracking which agent sections are populated vs pending

See .docs/data-model/source/ and .docs/data-model/target/ for detailed field documentation.

Project structure

src/cellarbrain/
├── cli.py            # CLI entry point with subcommands
├── reader.py         # CSV readers
├── parsers.py        # Field-level parsers
├── transform.py      # Normalisation and entity building
├── writer.py         # Parquet writer with Arrow schemas
├── validate.py       # Post-ETL validation
├── incremental.py    # Change detection and sync
├── markdown.py       # Dossier generation with agent section preservation
├── query.py          # DuckDB query layer (stats, search, SQL)
├── dossier_ops.py    # Dossier read/write/pending operations
└── mcp_server.py     # FastMCP server (7 tools, 8 resources, 4 prompts)

Development

Note: Unit tests and smoke tests require a source checkout of the repository. They are not included in the PyPI package.

# Clone and set up for development
git clone https://github.com/urban-buss/cellarbrain.git
cd cellarbrain
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate      # macOS / Linux
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run only unit tests (fast, no CSV files needed)
pytest tests/ -v --ignore=tests/test_integration.py

# Run integration tests (requires raw/*.csv files)
pytest tests/test_integration.py -v

License

Private — not for redistribution.