ferretproject/ferret repository overview

Try the demo⁠ · Install⁠ · Help⁠ · Discord⁠

Ferret is a home inventory you run yourself. Your household's properties, rooms and boxes; the things in them with photos, receipts and manuals; warranties, maintenance and stock — all on your own server, shared with the people you live with. And when you need something, Ferret tells you where it is.

⁠What it does

Add things fast, label boxes, find anything, keep receipts and warranties, schedule maintenance, track stock and the shopping list, remember what you lent, and print an insurance report. Claude can do all of it too, over MCP.

Add things fast Snap a photo, scan a barcode, or photograph a whole room and pick what to keep.	Boxes and QR labels Print labels for boxes and shelves; scan one to see what's inside.	Find anything Search by name, place or meaning — or just ask, “where's the drill?”
Receipts and warranties Keep receipts and manuals with each thing, and hear before a warranty runs out.	Maintenance Filters, tune-ups and checks on a schedule, with reminders when they're due.	Stock and shopping Track what runs out and keep the shopping list in step.
Lending Remember who borrowed the saw, and since when.	Insurance report Everything you own and what it's worth, ready for a claim, plus recall checks.	API and MCP A REST API for scripts, and an MCP server so Claude can look things up and add them.

⁠Why Ferret

• Your server, your data. One Docker container with SQLite. Uploads are encrypted at rest with a key per household; nightly backups with a restore check; Download everything any time.
• Households, not just accounts. Owners, admins, members and read-only viewers; invitations by email; single sign-on through your own identity provider.
• AI is optional. Point it at your own models (Ollama, any OpenAI-compatible server, docling) for suggestions from photos, receipts read for you, Ask Ferret and search by meaning. Nothing is applied without a tap.
• Made for the phone. An installable app that works offline, with barcode and QR scanning built in.

⁠Run it (Docker)

curl -O https://raw.githubusercontent.com/ferret-project/ferret/main/compose.yaml
curl -o .env https://raw.githubusercontent.com/ferret-project/ferret/main/.env.example
# In .env: AUTH_SECRET and FILES_KEY (each: openssl rand -base64 32), and PUBLIC_URL
docker compose up -d

The image is on GitHub's registry⁠ (ghcr.io/ferret-project/ferret) and Docker Hub⁠ (ferretproject/ferret) — the same tags on both (latest, or a release like 2026.11.2), for x86-64 and 64-bit ARM.

Then open PUBLIC_URL; the first account made is the server admin. Keep a copy of FILES_KEY somewhere safe — without it, uploaded files can't be read. Behind a reverse proxy, set TRUSTED_PROXIES to its address.

The help is built in at /docs: installing⁠, every setting⁠, AI⁠, backups⁠ and connecting Claude⁠.

⁠Use it with Claude (MCP)

Ferret has an MCP server built in at /mcp, so Claude (or any MCP client) can use your inventory for you:

• "Where did we put the tent?"
• "Add the new blender — it was $89 at Target, it's in the kitchen."
• "We used the last furnace filter." (stock goes down, and it's on the shopping list)
• "What maintenance is due this month, and when does the dishwasher warranty end?"

Make a key in Ferret (Household & settings → Claude & API → New key), then:

claude mcp add --transport http ferret https://ferret.example.com/mcp --header "Authorization: Bearer ferret_…"

Other clients that speak Streamable HTTP take the same address and header (X-API-Key: ferret_… works too):

{
  "mcpServers": {
    "ferret": {
      "type": "http",
      "url": "https://ferret.example.com/mcp",
      "headers": { "Authorization": "Bearer ferret_…" }
    }
  }
}

Clients that only start a local program and talk to it over stdio (Docker's MCP Toolkit, desktop apps' config files) can use the small bridge in contrib/mcp-bridge⁠: it forwards each message to your Ferret with the key. Ferret is also listed in the MCP Registry⁠ as io.github.ferret-project/ferret.

What Claude can do (40 tools):

Safe by design. A key acts for one person in one household, can be read-only (Claude can look and ask, but the tools that change things aren't offered) and can expire; revoke it any time. Viewers' keys are always read-only. Deleted things wait 30 days in Recently deleted, and nothing a model suggests from a photo or document is applied until someone confirms it.

⁠Develop

Requirements: Node 26+, pnpm 10 (npm install -g corepack && corepack enable).

cp .env.example .env      # AUTH_SECRET and FILES_KEY, as above
pnpm install
pnpm dev                  # server on :8787, web app on :5173
pnpm test
pnpm typecheck

⁠License

MIT⁠. Questions, ideas or something odd? Come say hi on Discord⁠.