Ferret

[Latest release] [MIT license] [Docker image] [Discord] [Ferret MCP server – quality and maintenance score on Glama]

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.

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.yamlcurl -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_URLdocker compose up -d

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_…" }    }  }}

What Claude can do (40 tools):

[Ferret MCP server – quality and maintenance score on Glama]

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 abovepnpm installpnpm dev                  # server on :8787, web app on :5173pnpm testpnpm typecheck

License

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

[图片]