Skip to main content
Glama
Home Inventory MCP

Home Inventory MCP

by ClemannD

Home Inventory MCP

Home Inventory keeps track of the things in your house: what you own, model and serial numbers, warranties, receipts, and manuals. You mostly use it by asking an AI assistant like ChatGPT or Claude, which reads and updates the inventory through MCP. There's also a web app for browsing, uploading files, and scanning paper documents with your phone.

It runs on your own Cloudflare account. One deployment holds one household's inventory, and everyone you add as a member sees the same data.

What it's for

Once your things are in it, you can ask your assistant questions like:

  • "What's the warranty on the living room TV?"

  • "My stove is acting up. How do I reset it?"

  • "Which warranties run out before spring?"

  • "What's the tracking number for the package I shipped to Mom?"

  • "I just bought a Bosch dishwasher at Lowe's for $1,049. Add it."

The assistant does the understanding. The inventory returns facts: the model number, the warranty end date and days left, the text of the manual you saved. When more than one item could match, the assistant asks which one you meant.

Related MCP server: HomeBoxMCP

What it stores

  • Items: the things themselves, with brand, model, serial, location, purchase details, photos, and any extra fields you want (filter size, paint color).

  • Warranties on items. An item can have several, for example the manufacturer's plus a credit card extension. Status and days left are computed from today's date in your time zone.

  • Entries: records that aren't items. Out of the box these are receipts, service records, and notes. An entry can link to an item or stand alone, so a receipt kept only for its tracking number works fine. Delete it when you're done with it.

  • Files: PDFs, photos, and links. Text is pulled out of PDFs and images, so a search for "reset" finds the page in your stove's manual.

How it works

Everything runs in one Cloudflare Worker:

  • /mcp is a remote MCP server. MCP clients connect with OAuth: you sign in, approve the app once, and it acts as you.

  • The web app is a React SPA served from the same Worker, behind sign-in.

  • Data lives in D1 (SQLite) with a full-text index. Files live in a private R2 bucket. OAuth tokens live in KV.

  • Sign-in is by email code or passkey. Codes are sent with Cloudflare Email Service.

  • Mail forwarded to your ingest address arrives through Cloudflare Email Routing and becomes an entry with its attachments.

  • Workers AI converts PDFs and images to text for search. It's optional.

  • A daily cron emails members about warranties ending in 30 and 7 days.

Requirements

  • A Cloudflare account with a domain on it. The app is served on a host in that zone, like home.example.com.

  • Email Sending enabled for a domain in the account, for sign-in codes and reminders. Without it you can only sign in with a passkey, and you need email to sign in the first time.

  • Email Routing on the domain, if you want to forward receipts.

  • Node.js 22 or newer. Developed on Node 24 with Wrangler 4.

Setup

  1. Fork and clone the repo, then install:

    npm install
    npx wrangler login
  2. Run setup. It creates the D1 database, R2 bucket and KV namespace (or reuses them if they exist), writes wrangler.jsonc, and applies the database migrations:

    npm run setup -- --domain home.example.com --owner you@example.com

    It asks for the sender and ingest addresses. All options are listed at the top of scripts/setup.ts. wrangler.jsonc is gitignored because it holds your account's resource IDs.

  3. Enable Email Sending for the domain you send from. Use the dashboard (Email Service) or:

    npx wrangler email sending enable example.com
  4. Deploy:

    npm run deploy
  5. To forward receipts, add an Email Routing rule that sends your ingest address (for example inventory@example.com) to the Worker, and turn on subaddressing under Email Routing → Settings so plus addresses like inventory+note@example.com reach it too.

  6. Open the site and sign in with the owner address. You'll get a code by email. Then:

    • add a passkey under Passkeys, so you don't need codes;

    • add household members under Household;

    • connect your assistant under Connect an assistant.

The owner is created from OWNER_EMAIL the first time someone asks for a sign-in code while there are no users. After that, only the owner can add or remove members.

Connecting an assistant

The server URL is https://<your domain>/mcp. The app shows it under Connect an assistant.

  • Claude: Settings → Connectors → Add custom connector, then paste the URL.

  • ChatGPT: turn on developer mode and add a custom app (connector) with the URL and OAuth sign-in. Menu names, and which plans can add custom apps, change over time.

  • Other MCP clients: anything that supports remote MCP servers with OAuth and dynamic client registration.

When the client connects, you sign in and approve it. Each member connects as themselves. Members can see and disconnect their connections in the same settings page. Removing a member stops their connections working.

The tools cover searching, reading full records and file text, creating and updating items, warranties and entries, attaching links (optionally downloading a copy), uploading files, deleting records, and managing the email allowlist. Read tools are marked read-only, so clients can skip asking you before they run. delete is marked destructive.

Files

Assistants can't pass a file you attach in chat to an MCP tool, so there are two ways in:

  • create_upload_link returns a link for one item or entry. You open it on any device and pick files or take a photo, without signing in. It accepts one upload (several files are fine) and expires after an hour. An agent that has the file and network access to your domain can post it itself (curl -F file=@invoice.pdf <link>); scripts get JSON back.

  • upload_file takes a file's bytes as base64, up to 10 MB. It's for clients that have the original file, such as an agent reading from disk. The server checks the first bytes against the declared type, so a file the model tried to rebuild from what it saw is rejected rather than saved broken.

Email inbox

Forward a receipt or order confirmation to your ingest address and it becomes a receipt entry. The email body is saved as the entry's text, and attachments are saved as its files.

  • Only senders on the allowlist are accepted. Everything else is rejected. The check uses the envelope sender, so forward from the address you allowed. Manage the list in Email inbox or ask your assistant.

  • The part after a plus says where the message goes:

    • inventory+note@example.com, inventory+service@example.com: a new entry of that type. Unknown types become receipts.

    • inventory+itm_…@example.com: a new receipt linked to that item.

    • inventory+ent_…@example.com: added to that entry. Attachments become its files; a message without attachments is appended to its notes.

    Each item and entry page shows its address, and the MCP tools return it as email_to, so an assistant with access to your mail can forward an invoice straight to the right record. Plus addresses only reach the Worker with subaddressing turned on: Email Routing → Settings, or support_subaddress in the Email Routing API.

Adding a record type

Entry types are defined in shared/entry-types.ts. Each type gets a tab in the web app, a form, and a description the MCP tools pass to the assistant. Fields are stored as JSON, so adding a type doesn't need a migration:

{
  id: "subscription",
  label: "Subscriptions",
  singular: "Subscription",
  description: "Recurring services: streaming, software, memberships. Track the renewal date and price.",
  fields: [
    { key: "price", label: "Price", kind: "money" },
    { key: "renews_on", label: "Renews", kind: "date" },
    { key: "account", label: "Account email", kind: "text" }
  ],
  columns: ["price", "renews_on"]
}

Don't rename a type's id once you have entries of that type. Existing rows keep the old value.

Configuration

npm run setup writes these to vars in wrangler.jsonc. Edit and redeploy to change them.

  • PUBLIC_URL: the site's origin. Used for OAuth metadata and links in tool results and emails.

  • OWNER_EMAIL: the first member, created when there are no users.

  • EMAIL_FROM: sender for codes and reminders, like Home Inventory <inventory@example.com>. Its domain must have Email Sending enabled.

  • INGEST_ADDRESS: shown in the app as the address to forward to. The routing rule is what actually delivers mail.

  • TIMEZONE: IANA zone for "today" in warranty math and reminder timing. Defaults to UTC.

  • CURRENCY: ISO 4217 code for displaying prices. Defaults to USD.

  • APP_NAME: shown in the app, emails, and the consent page.

Remove the ai binding to turn off text extraction. Uploads still work, but PDFs and images aren't searchable by their contents.

Local development

npm run setup -- --local --owner you@example.com
npm run dev

Open http://localhost:5173 and sign in with the owner address. With --local, no email is sent: the code is printed in the terminal running npm run dev. Passkeys work on localhost.

npm test            # Worker tests in workerd: auth, catalog, OAuth + MCP, email ingest
npm run typecheck

Local dev has no Workers AI binding, so files other than plain text aren't converted.

Costs

Usage for one household is small. Check Cloudflare's current pricing for Workers, D1, R2, KV, Email Service and Workers AI before you deploy. Text extraction from images runs a Workers AI model, so it counts toward Workers AI usage.

License

MIT. See LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables cataloging and managing personal inventory (items, attachments) through natural language, allowing users to add, search, update, and retrieve item details and attachments via MCP tools.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables natural-language read and write access to a Homebox inventory, including searching and managing items, locations, tags, and attaching files such as receipts and warranties.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to read current pantry inventory and low-stock shopping needs, export a shopping queue, and perform idempotent inventory adjustments and catalog link management through remote MCP tools.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables managing a personal pantry, shopping lists, cookbook recipes, and saved receipts remotely through MCP tools using natural language or API calls.
      -