# AllOurThings — Full Reference

> AI-powered personal inventory management. Catalog everything you own and ask natural language questions about your stuff — appliances, warranties, manuals, electronics, collectibles, and more. Privacy-first: your data stays in a folder you control, never uploaded to any server.

## Product overview

AllOurThings is a household inventory system with a local MCP server that integrates with Claude Desktop. Users catalog their possessions and then ask natural language questions about them via AI.

Homepage: https://allourthings.io
Documentation: https://allourthings.io/docs
MCP server npm package: @allourthings/mcp-server
CLI npm package: @allourthings/cli

## MCP server setup

The AllOurThings MCP server runs locally via npx. No hosted endpoint — data never leaves the user's device.

### Claude Desktop configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "allourthings": {
      "command": "npx",
      "args": ["-y", "@allourthings/mcp-server"]
    }
  }
}
```

### Environment variables

- `ALLOURTHINGS_DATA_DIR` — path to inventory folder. Defaults to `~/Documents/AllOurThings`.

### Data directory

Each item is stored as a directory: `<data-dir>/items/<slug>-<id>/item.json`. Attachments live alongside the JSON file in the same directory.

## MCP tools reference

### add_item
Add a new item to the inventory.

Parameters:
- `name` (required) — item name
- `category` — e.g. appliance, electronics, furniture, collectible
- `subcategory` — optional secondary grouping (e.g. large appliance, laptop)
- `brand` — manufacturer or brand name
- `model` — model name or number
- `purchase_date` — ISO date (e.g. 2024-01-15)
- `purchase_price` — numeric price paid
- `currency` — currency code (e.g. GBP, USD, EUR)
- `warranty_expires` — ISO date
- `retailer` — where purchased
- `notes` — free-text notes
- `tags` — array of strings for grouping/searching
- `serial_number` — device serial number
- Any custom fields are also accepted and preserved (e.g. `condition`, `edition`, `insured_value`)

### get_item
Get a single item by ID or name. Tries exact ID match, then exact name match, then substring match.

Parameters:
- `id_or_name` (required)

### get_item_fields
List all field names currently in use across the inventory. Useful for discovering what fields exist before filtering or querying.

Parameters: none

### list_items
List all items, optionally filtered.

Parameters:
- `category` — filter by category
- `subcategory` — filter by subcategory
- `tags` — array of tags (all must match)

### update_item
Update fields on an existing item.

Parameters:
- `id` (required) — item ID
- `updates` (required) — object of fields to update

### delete_item
Hard-delete an item by ID.

Parameters:
- `id` (required)

### search_items
Full-text search across all item fields. Max query length 200 chars.

Parameters:
- `query` (required)

### add_attachment
Attach a file to an item. Contents must be base64-encoded.

Parameters:
- `item_id` (required)
- `filename` (required) — e.g. manual.pdf
- `data_base64` (required) — base64-encoded file contents
- `label` — human-readable label (e.g. "Washing machine manual")

### get_attachment
Retrieve an attachment's contents as base64.

Parameters:
- `item_id` (required)
- `filename` (required)

### delete_attachment
Delete an attachment from an item.

Parameters:
- `item_id` (required)
- `filename` (required)

### attach_from_url
Download a file from a URL and attach it to an item.

Parameters:
- `item_id` (required)
- `url` (required) — URL of the file to download
- `filename` (required)
- `label` — human-readable label

## Item schema

Required fields: `id`, `name`, `created_at`, `updated_at`

Well-known optional fields: `category`, `subcategory`, `brand`, `model`, `purchase_date`, `purchase_price`, `currency`, `warranty_expires`, `retailer`, `features`, `notes`, `tags`, `serial_number`, `attachments`

The schema uses passthrough — unknown custom fields are preserved as-is. Users can store any additional fields they need.

## Privacy model

- No account required
- No data uploaded to any server
- Inventory is a folder of plain JSON files
- The MCP server reads from that folder directly via local process
- Compatible with any folder-sync service: iCloud, Dropbox, local disk
- AI integration (Claude Desktop) reads via the local MCP process — nothing passes through AllOurThings servers

## Pricing

AllOurThings is currently free to use. See https://allourthings.io/pricing.md for current pricing details.

## CLI reference

The AllOurThings CLI (`@allourthings/cli`) provides terminal access to the same inventory. Useful for scripting, automation, and agents that prefer subprocess invocation over MCP.

Install: `npx @allourthings/cli`

Commands:
- `search <query>` — full-text search
- `list [--category] [--subcategory] [--tag]` — list with optional filters
- `fields` — list all field names in use across the inventory
- `get <id-or-name>` — get a single item
- `add <name> [fields...]` — add an item
- `update <id> [fields...]` — update an item; use `--set key=value` for custom fields
- `delete <id> [--yes]` — delete an item
- `attach add <item-id> <file>` — attach a local file
- `attach url <item-id> <url>` — download and attach from URL
- `attach get <item-id> <filename>` — save attachment to disk
- `attach rm <item-id> <filename>` — delete an attachment

Global flags: `--data-dir <path>`, `--json` (machine-readable output), `--version`

## Tech stack

- MCP server: TypeScript, published to npm as @allourthings/mcp-server
- CLI: TypeScript, published to npm as @allourthings/cli
- Storage core: Rust (allourthings-core), published to crates.io and npm as @allourthings/core
- Transport: stdio (MCP standard)
- Runtime: Node.js via npx

## Links

- [Homepage](https://allourthings.io)
- [Documentation](https://allourthings.io/docs)
- [Pricing](https://allourthings.io/pricing.md)
- [MCP server on npm](https://www.npmjs.com/package/@allourthings/mcp-server)
- [CLI on npm](https://www.npmjs.com/package/@allourthings/cli)
- [Source on GitHub](https://github.com/matt-harding/allourthings-mcp)
- [Core library on crates.io](https://crates.io/crates/allourthings-core)
- [MCP manifest](https://allourthings.io/.well-known/mcp/manifest.json)
- [Agent card](https://allourthings.io/.well-known/agent-card.json)