Boxes MCP

An unofficial, local-first Model Context Protocol server for inventory data exported from Boxes: Storage made simple.

Boxes MCP turns your spaces, containers, nested items, values, custom fields, and downloaded photos into a private mirror that an MCP client can search and analyze. Boxes remains the capture app and source of truth.

This project is not affiliated with, endorsed by, or sponsored by StackTracks, LLC. “Boxes” is used only to identify compatibility with the Boxes app. No Boxes logos or proprietary code are included.

Status

Early preview. The server, format-tolerant CSV/ZIP importer, signed webhook verifier, and export-request adapter are implemented. Exact field mapping will be tightened against a sanitized real export.

The package is named boxes-home-inventory-mcp because the npm name boxes-mcp is already used by an unrelated GNOME virtualization project.

Related MCP server: literature-evidence-mcp

Quick start

Requires Node.js 20 or newer.

npm install
npm run build
node dist/src/cli.js import /path/to/boxes-export.zip
node dist/src/cli.js serve

Add the local server to an MCP client:

{
  "mcpServers": {
    "boxes": {
      "command": "node",
      "args": ["/absolute/path/to/boxes-mcp/dist/src/cli.js", "serve"],
      "env": {
        "BOXES_MCP_DATA_FILE": "/absolute/private/path/inventory.json",
        "BOXES_MCP_MEDIA_DIR": "/absolute/private/path/media"
      }
    }
  }
}

Inventory data and images are ignored by Git. Do not commit real exports or your data/ directory.

Tools

• search_inventory — search names, notes, locations, tags, and custom fields.

• get_inventory_object — fetch a record by stable ID.

• list_contents — list the objects directly inside a space or container.

• inventory_totals — summarize counts, quantity, and declared value.

• documentation_audit — find items missing photos, values, receipts, or other requested evidence.

• get_sync_status — inspect import/webhook freshness.

• request_export — call a Boxes-approved export endpoint when one is configured.

Importing exports and images

Request an export in Boxes from Dashboard → Manage Data → Export Data. Import the downloaded CSV, a directory of CSVs, or a ZIP containing CSVs:

boxes-mcp import ~/Downloads/boxes-export.zip

If your image ZIP is separate, import it too. Image files are copied into the private media directory with SHA-256 filenames so duplicates are stored once.

The importer preserves every original column in raw, even when it does not recognize the field yet.

Export-request automation

Boxes currently documents export requests through its iOS interface, not a public API. Its terms prohibit reverse-engineering and unauthorized automated access. For that reason, this project does not embed private mobile endpoints or ask for your Boxes password.

The MCP tool is ready for an approved endpoint. Once Boxes provides an export URL and authentication method, configure:

BOXES_EXPORT_REQUEST_URL=https://approved.example/export
BOXES_EXPORT_REQUEST_TOKEN=...
BOXES_EXPORT_ALLOWED_HOSTS=approved.example

Until then, request_export returns a clear not_configured result instead of pretending an export was requested.

Event notifications

Pro accounts can send signed HTTPS event notifications to Boxes MCP:

BOXES_WEBHOOK_SECRET=... boxes-mcp webhooks

The receiver listens on POST /webhooks/boxes, verifies the X-Boxes-Signature HMAC over timestamp.raw_body, rejects stale requests, and deduplicates event UUIDs. It stores the entity snapshot while discarding actor email and device metadata by default.

Webhooks are an incremental signal, not a complete backup. Use periodic full exports to reconcile missed events and photos.

Privacy and security

• Local storage by default; no analytics or telemetry.

• Raw exports, photos, secrets, and the mirror database are Git-ignored.

• Actor email/device metadata from webhooks is not retained.

• Export endpoints require HTTPS and an explicit hostname allowlist.

• Read tools are marked read-only in their MCP annotations.

See SECURITY.md before exposing the HTTP receiver to the internet.

Development

npm run typecheck
npm test

Contributions are welcome. Synthetic fixtures only—never attach a real household export to a public issue or pull request.

License

Apache-2.0.