Ferret

io.github.ferret-projectPublished by GitHub account ferret-projectv2026.11.1Updated Nov 5, 2026

Self-hosted home inventory: find, add and update what you own, maintenance, warranties.

VerifiedStreamable HTTPWeb executableProductivity & WorkflowFiles & Storage

Overview

AI-generated overview

Ferret is a self-hosted home inventory; its MCP endpoint lets an assistant find, add and update household items, places, warranties and maintenance.

What you can do
  • Search and ask: find items by words or meaning, answer questions from receipts and manuals, browse places, history and recently deleted items
  • Add and change: add items (including from photos), update, move, delete and restore items, properties and rooms
  • Upkeep: track maintenance by date or usage, warranties and claims, service providers
  • Household: manage stock and the shopping list, lending, barcodes, collections, insurance report and coverage check, what needs attention
When to use it
Useful when you run Ferret for your household and want an assistant to answer "where is it?" questions, record new purchases, log used-up stock, or check upcoming maintenance and warranty expiry without opening the app.
Requirements
A running Ferret server reachable over Streamable HTTP at its /mcp path, plus an API key created in Ferret under Claude & API, sent in the X-API-Key header (or as a Bearer token). The server itself runs as a Docker container with SQLite and needs AUTH_SECRET, FILES_KEY and PUBLIC_URL configured.
Before you install
The API key acts for one person in one household; keep it secret, scope it read-only where possible and revoke it when done. Write tools can add, move, delete and restore items and change stock, so changes reach real household data. Keep a copy of FILES_KEY, since uploaded files cannot be read without it. Deleted items stay recoverable for 30 days.

Installation

In SourceWeft

  1. Open Ferret in the dashboard and add it to a workspace.
  2. Connect X-API-Key credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Other MCP clients

Follow the launch instructions in the repository.

README

[Ferret — find anything you own. A self-hosted home inventory for your household.]

[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.

[Ferret on a phone: the home page, a room with the things kept in it, and maintenance that's due.]

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.

[Image]
Add things fast
Snap a photo, scan a barcode, or photograph a whole room and pick what to keep. 		[Image]
Boxes and QR labels
Print labels for boxes and shelves; scan one to see what's inside. 		[Image]
Find anything
Search by name, place or meaning — or just ask, “where's the drill?”
[Image]
Receipts and warranties
Keep receipts and manuals with each thing, and hear before a warranty runs out. 		[Image]
Maintenance
Filters, tune-ups and checks on a schedule, with reminders when they're due. 		[Image]
Stock and shopping
Track what runs out and keep the shopping list in step.
[Image]
Lending
Remember who borrowed the saw, and since when. 		[Image]
Insurance report
Everything you own and what it's worth, ready for a claim, plus recall checks. 		[Image]
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)

bash
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:

bash
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):

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

What Claude can do (40 tools):

Findsearch by words and meaning, ask questions answered from receipts and manuals, items, places, history, recently deleted
Add and changeadd items (also from a photo, or a whole room's photos), update, move, delete and restore; properties and rooms
Upkeepmaintenance by date or by use (odometer, engine hours), warranties and claims, service providers
Householdstock and the shopping list, lending, barcodes, collections, the insurance report and coverage check, what needs attention

[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).

bash
cp .env.example .env      # AUTH_SECRET and FILES_KEY, as abovepnpm installpnpm dev                  # server on :8787, web app on :5173pnpm testpnpm typecheck
PathWhat
apps/serverHono API, Better Auth, Drizzle + SQLite; MCP server; adapters behind ports (src/ports.ts)
apps/webReact 19 + Vite + Tailwind v4 + FlyonUI PWA
apps/docsThe help (VitePress), served at /docs
packages/sharedZod schemas and helpers shared by the server and the web app

License

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

[Image]

Source: README.md at commit 1b8a59b

Tools

0
This server asks for a credential such as an API key, so SourceWeft could not read its tools without one and has not indexed them.

Version history

1
  1. v2026.11.1LatestNov 5, 2026

Score

60% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts