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.

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". On failure, isError: true is set and the text describes the problem. Item not found is a soft error — the tool returns an empty result rather than throwing.

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

The data directory defaults to ~/Documents/AllOurThings. Override with --data-dir <path> or the ALLOURTHINGS_DATA_DIR environment variable.

Commands

• search <query> — full-text search across all item fields
• list — list all items, optionally filtered by --category, --subcategory, --tag
• get <id-or-name> — get a single item by ID or name
• add <name> — add a new item (accepts all standard fields as flags)
• update <id> — update fields on an existing item; use --set key=value for custom fields
• 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
• 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 inventory data directory
• --json — output raw JSON instead of formatted text (useful for scripting)
• --version — print the CLI version

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. Any fields not listed below are accepted as custom fields and stored as-is.

// 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   // ISO date, e.g. "2024-01-15"
purchase_price: number
currency: string        // e.g. "GBP", "USD"
warranty_expires: string // ISO date
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.

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.

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

delete_item

Permanently delete an item by ID.

id: string  // required

search_items

Full-text search across all item fields.

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

item_id: string  // required
url: string      // required — must be a valid URL
filename: string // required
label: string    // optional