Documentation

What is the MCP server?

The AllOurThings MCP server connects your inventory to AI assistants that support the Model Context Protocol — currently Claude Desktop. Once connected, you can ask plain-English questions about everything in your inventory.

The server reads directly from the same folder used by the iOS app, so everything stays in sync with no extra setup.

Setting up with Claude Desktop

Add the following to your Claude Desktop configuration file, then restart Claude Desktop. Your inventory folder path should match the one you set up in the iOS app.

{
  "mcpServers": {
    "allourthings": {
      "command": "npx",
      "args": ["-y", "@allourthings/mcp-server", "--data-dir", "~/Documents/AllOurThings"]
    }
  }
}

Change --data-dir to match the folder you chose in the iOS app. If you're using iCloud Drive, the path will be something like ~/Library/Mobile Documents/com~apple~CloudDocs/AllOurThings.

A vault folder is required. Instead of --data-dir you can set the ALLOURTHINGS_DATA_DIR environment variable, or run npx @allourthings/cli init once to save the folder for both the MCP server and the CLI.

Example questions you can ask

• When does my dishwasher warranty expire?
• Where did I put the router manual?
• What electronics do I own?
• How much did I spend on appliances last year?
• Do I have the receipt for the TV?
• What Pokémon cards do I have graded?

For agents

When to use AllOurThings: route tasks to the AllOurThings MCP server when the user asks about items they own — warranties, manuals, purchase history, serial numbers, or general inventory queries. Call get_item_fields first to discover what fields this user's catalog actually contains, then use search_items for open-ended questions and list_items with filters for structured lookups.

When not to use it: AllOurThings only knows what the user has catalogued. It has no knowledge of products in general, pricing data, or the wider web. If the user asks about a product they haven't added, there will be no results.

Authentication: none required. The MCP server is a local process that reads directly from the user's data directory. There are no API keys, tokens, or OAuth flows. Access is granted implicitly by the user configuring the server in their MCP client.

Rate limits: none. The server is a local process with no network calls — throughput is limited only by local disk I/O.

Errors: tools return a content array with type: "text". Any failure — invalid or unknown arguments, a missing item, a duplicate name, an invalid date — sets isError: true and the text describes the problem. Looking up an item that doesn't exist with get_item returns a "No item found" message rather than an error.

What is the CLI?

The AllOurThings CLI lets you manage your inventory from the terminal — no app or AI client required. It reads from the same data folder as the iOS app and MCP server, so everything stays in sync.

It's useful for power users who prefer the terminal, for scripting and automation, and for agents that prefer spawning a subprocess over an MCP connection.

Installation

Run without installing (recommended):

npx @allourthings/cli <command>

Or install globally for repeated use:

npm install -g @allourthings/cli

Run allourthings init once to choose your vault folder. It's saved to a config file that the MCP server also reads. Override it with --data-dir <path> or the ALLOURTHINGS_DATA_DIR environment variable.

Commands

• init [path] — choose your vault folder (run once)
• search <query> — search field values; every word must match
• list — list all items, optionally filtered by --category, --subcategory, --tag
• get <id-or-name> — get a single item by ID or name (if a name matches several items, the error lists their IDs)
• add <name> — add a new item (accepts all standard fields as flags; names must be unique)
• update <id> — update fields on an existing item; use --set key=value for any field and --unset <field> to remove one. An empty value such as --notes "" also clears a field
• delete <id> — delete an item (prompts for confirmation; skip with --yes)
• fields — list all field names currently in use across your catalog
• attach add <item-id> <file> — attach a local file to an item
• attach url <item-id> <url> — download a file from a URL and attach it
• attach get <item-id> <filename> — save an attachment to disk (-o - writes to stdout)
• attach rm <item-id> <filename> — delete an attachment

Examples

# Search for anything dishwasher-related
npx @allourthings/cli search dishwasher

# List all electronics
npx @allourthings/cli list --category Electronics

# List laptops specifically
npx @allourthings/cli list --subcategory Laptop

# Add an item
npx @allourthings/cli add "Bosch Dishwasher" \
  --category Appliances \
  --subcategory "Dishwasher" \
  --brand Bosch \
  --warranty 2027-06-01

# Attach a manual PDF
npx @allourthings/cli attach add <item-id> bosch-manual.pdf

# See all fields in use across your catalog
npx @allourthings/cli fields

# Output as JSON for scripting
npx @allourthings/cli --json list --category Appliances

Global flags

• --data-dir <path> — path to the vault folder (overrides init and ALLOURTHINGS_DATA_DIR)
• --json — output raw JSON instead of formatted text (useful for scripting); errors go to stderr as {"error": "..."}
• --version — print the CLI version

Errors print a single error: ... line and exit with status 1.

Overview

The AllOurThings MCP server exposes 11 tools over the Model Context Protocol (stdio transport). All tools are available once the server is running — no authentication required. See the full reference in llms-full.txt or the MCP manifest.

get_item_fields

Return all field names currently in use across your catalog. Call this before adding or updating items to discover what fields exist and use consistent naming.

// No parameters required

add_item

Add a new item to the inventory. Names must be unique. Any fields not listed below are accepted as custom fields and stored as-is; id, created_at, updated_at and attachments are managed automatically.

// Required
name: string

// Optional — well-known fields
category: string        // e.g. "Electronics", "Appliances"
subcategory: string     // e.g. "Laptop", "Coffee Machine"
brand: string
model: string
purchase_date: string   // YYYY-MM-DD, e.g. "2024-01-15"
purchase_price: number  // non-negative
currency: string        // e.g. "GBP", "USD"
warranty_expires: string // YYYY-MM-DD
retailer: string
location: string        // e.g. "kitchen", "garage"
notes: string
tags: string[]

// Any other fields are accepted as custom fields
// e.g. serial_number, policy_number, account_number

get_item

Get a single item by ID or name. Tries exact ID match, then exact name match, then substring match. If a name matches more than one item, the error lists their IDs.

id_or_name: string  // required

list_items

List all items, optionally filtered. All filters are optional and can be combined.

category: string    // filter by category (exact match)
subcategory: string // filter by subcategory (exact match)
tags: string[]      // filter by tags — all must match

update_item

Update fields on an existing item. Only the fields you provide are changed; set a field to null to remove it.

id: string          // required — item ID
updates: object     // required — e.g. { warranty_expires: "2027-01-15", notes: null }

delete_item

Permanently delete an item by ID.

id: string  // required

search_items

Case-insensitive search over field values (not field names). Every word in the query must appear in some field.

query: string  // required

add_attachment

Attach a file to an item (manual, receipt, photo, warranty document). File contents must be base64-encoded.

item_id: string      // required
filename: string     // required — e.g. "manual.pdf" (no slashes; "item.json" is reserved)
kind: string         // required — "manual" | "receipt" | "photo" | "warranty" | "other"
data_base64: string  // required — base64-encoded file contents
label: string        // optional — e.g. "Washing machine manual"

get_attachment

Retrieve an attachment's contents as a base64-encoded string.

item_id: string  // required
filename: string // required

delete_attachment

Delete an attachment from an item.

item_id: string  // required
filename: string // required

attach_from_url

Download a file from a URL and attach it to an item — useful for PDF manuals or warranty documents. The item and filename are checked before anything is downloaded.

item_id: string  // required
url: string      // required — must be a valid URL
kind: string     // required — "manual" | "receipt" | "photo" | "warranty" | "other"
filename: string // optional — defaults to the server's Content-Disposition name or the final URL
label: string    // optional