Potluck

Privacy-first personal knowledge database for your AI — local-first, MCP-native.

Potluck ingests your data exports (Google Takeout first: Keep + Gmail; more sources each phase), stores everything in one local SQLite database, and exposes it three ways — a web app, a CLI, and MCP for AI assistants. No cloud, no telemetry: nothing leaves your machine.

Status — v1 rewrite in progress

Full plan, architecture, and locked decisions: pinned issue #98. v0 is archived at archive/v0.

Quickstart — 60 seconds to running

Requires uv (Python is fetched automatically).

1 — Start the server. Straight from GitHub:

uvx --from git+https://github.com/DoubleGremlin181/potluck potluck serve

CLI, API, and MCP are fully functional in this form; only the web app is not bundled (the page at / says so and points at the API docs). Release wheels ship with the web app embedded:

uvx --from https://github.com/DoubleGremlin181/potluck/releases/download/v1.0.0-beta.1/potluck-1.0.0b1-py3-none-any.whl potluck serve

Or Docker (web app included; data persists in the potluck-data volume):

docker run -p 127.0.0.1:8765:8765 -v potluck-data:/data ghcr.io/doublegremlin181/potluck:1.0.0-beta.1

2 — Import your data. Feed it a Google Takeout export (Keep + Gmail today; zip, tgz, or unpacked dir) — reuse the same uvx --from … potluck prefix for every command, or upload from the web app's Imports page:

uvx --from git+https://github.com/DoubleGremlin181/potluck potluck import ~/Downloads/takeout-20260707T120000Z-001.zip

3 — Search it.

uvx --from git+https://github.com/DoubleGremlin181/potluck potluck search "garden fence"

The web app lives at http://127.0.0.1:8765 — potluck serve opens it for you. Search and browse everything, start imports, and watch their progress live.

[!WARNING] Potluck is localhost-only by design — there is no authentication in v1. Do not expose it to other machines or the internet.

MCP for AI assistants

stdio (Claude Desktop, Claude Code, …):

{
  "mcpServers": {
    "potluck": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DoubleGremlin181/potluck", "potluck", "mcp"]
    }
  }
}

Streamable HTTP instead: potluck serve exposes the same tools at http://127.0.0.1:8765/mcp — one server surface for web app, API and MCP.

Toolset: search (keyword search with ranked, snippeted hits), list_items (browse/filter without a query), get_item (full content by id), get_thread (the whole email conversation around an item), get_stats (database overview), list_sources (what this build can ingest).

Setup guides — Claude Desktop, Claude Code, OpenClaw, Hermes, direct REST without MCP, and troubleshooting: docs/ai-integration.md.

CLI

potluck import PATH  ingest an export (Google Takeout zip/tgz/dir; auto-detected)
potluck search Q     full-text search (--kind, --prefix, --cursor, --limit, --json)
potluck list         browse items without a query (--kind, --source, --since, --sort, --json)
potluck show ID      full item content + metadata (--thread: the whole conversation)
potluck status       database overview + per-import stats
potluck serve        web app + API + MCP (/mcp) on one port (opens your browser)
potluck mcp          MCP server on stdio (HTTP lives at /mcp on the serve port)
potluck bench run    benchmark harness (smoke/full tiers)
potluck dev          source-plugin scaffolding (new-source / check-source)

Search queries can carry inline operators, combinable with each other and free text: from:[email protected] (or a name prefix: from:alice), source:gmail, kind:email, after:2024-01-01 (inclusive), before:2025-06-30 (exclusive), with quoted values supported. Source values are case-insensitive and spaces map to underscores, so source:"google keep" ≡ source:google_keep. Invalid operator values are ignored — the response's warnings list says what was dropped — and unknown key:value pairs are searched as plain text. Operators alone (no free text) list the matching items newest-first.

Search-as-you-type: --prefix (CLI) / prefix=true (MCP) matches the last word as a prefix (gar finds garden/garlic/garnet). Pagination uses opaque keyset cursors — pass a response's next_cursor back as cursor for the next page; the result set is frozen at the first page, so items ingested mid-pagination never shift, repeat, or hide existing hits.

Configuration is optional: defaults work out of the box. Override via POTLUCK_* env vars or ~/.config/potluck/config.toml (env > toml > defaults); the database lives at ~/.local/share/potluck/potluck.db by default.

Development

git clone https://github.com/DoubleGremlin181/potluck && cd potluck
uv sync && uv run pre-commit install
(cd web && npm ci && npm run build)
uv run potluck serve

Tests: uv run pytest (unit tier), -m browser for the Playwright smoke. Conventions live in CLAUDE.md; test patterns in tests/README.md.

License

MIT