Thingery

Thingery

Thingery is the open item database and MCP server for AI agents to list, find, and trade second-hand goods.

Say *"sell this"* to your AI assistant — it identifies the item, writes the listing, prices it, and publishes it. Say *"find me a used camera under €300"* — it searches every listing and proposes the best one. Thingery is the shared database and the MCP tools underneath those agents.

• Free for everyone. No take rate, no platform lock-in.
• Open source (Apache-2.0). Self-host the whole thing, or use the flagship instance.
• Agent-native: every capability is an MCP tool; any LLM can drive it.
• Self-hostable: Postgres + pgvector + Node 20.

Chinese-market name: 物坊 (Wùfāng).

MCP tools

Order flow

Orders close a deal on-platform. Stripe mode (buyer protection: platform charges the buyer, holds funds, pays the seller after delivery + dispute window) runs when the deployment has Stripe configured *and* the seller finished payout onboarding; otherwise orders run in off-platform mode — Thingery tracks state and deadlines, parties settle payment themselves. States: pending → sold → label_issued → in_transit → delivered → payout_pending → paid_out with disputed/cancelled/refunded off-ramps; deadlines are enforced by a server-side sweep (unpaid cancels 24h, dispute window 48h, never-shipped disputes auto-refund 72h — defaults, env-tunable). Design record: ADR 0003.

Sellers authenticate with OAuth (one-click sign-in from any MCP host — see below) or a thg_... API key (Authorization: Bearer); search is anonymous.

Buyer alerts (saved searches)

A buyer who finds nothing good can save the search as an intent; when a matching listing publishes later, their agent reads it as a match on the next session — no email, the buyer's agent pulls my_matches (design record: ADR 0006). Fan-out is bounded: each match is inserted at most once per (intent, item), at most 10 new matches per buyer per day, at most 100 per published listing, and a seller never matches their own listing.

Photo-required publishing

New listings need at least one photo to be visible to buyers — browse, search_items, and category counts all exclude photoless listings (a single derived predicate; design record: ADR 0005). What that means in practice:

• create_listing with zero images succeeds — the listing is created but pending: hidden from feeds, its item page shows placeholder art and is noindex. The result carries photo_required, visible: false, and next_steps pointing at add_item_image (or the item page, where the owner can snap a photo in two taps).
• The first photo publishes it — no second call needed. add_item_image returns visible: true; pending items carry needs_photo: true everywhere items are returned (get_item, my_listings, …).
• Deleting the last photo returns the listing to pending (hidden again); pre-rollout listings are grandfathered and stay live without photos — on thingery.dev that means created before 2026-10-27; a self-hosted instance grandfathers whatever exists when it first deploys this version.
• Owners manage photos on the item page (upload, delete, reorder) via the session-cookie routes documented in docs/item-images.md.

Two ways to use it

• Zero-config (everyone): open `/chat.html` on any deployment and talk to the Thingery assistant — describe an item to sell or to find. Searching needs no account; publishing needs a free one (/login.html, email + password; your MCP API key is shown after signup). The chat uses an LLM configured on the server (LLM_* env vars) — you bring the key, any OpenAI-compatible endpoint works; without it, chat is disabled while MCP and signup still work.
• Bring your own agent (power users): point any MCP client at /mcp and sign in with OAuth — Claude Desktop, ChatGPT connectors, VS Code and Inspector discover the sign-in flow automatically (RFC 9728 resource metadata + RFC 7591 dynamic client registration); you approve once on a consent screen and the host gets a rotating thgo_ token, with revoke-anytime at /apps. Prefer a key? The manual thg_... API key still works, and self-hosting is below (npx thingery over stdio).

Quickstart

Pick your mode first — hosted and self-hosted expose the same MCP tools but not the same data: listings you create on the hosted service are visible to everyone; listings on your self-hosted instance live only in your database.

Mode A — hosted: search in one minute

No install. Add https://thingery.dev/mcp as a remote HTTP server in your MCP client (Claude Desktop, ChatGPT connectors, VS Code, Inspector — see Connect an MCP client below) and sign in with OAuth, or grab an API key at /login.html (free account; the thg_... key is shown after signup). Searching needs no account at all — verify the wire format with curl:

curl -s https://thingery.dev/mcp \

-H 'content-type: application/json' \ -H 'accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call", "params":{"name":"search_items","arguments":{"q":"Air Max"}}}'

Responses come back as Server-Sent Events; the JSON-RPC result is on the data: line.

Mode B — self-hosted: the npm package

The thingery npm package runs the whole server against your own Postgres. No git clone needed:

mkdir my-thingery && cd my-thingery

npm install thingery

1. a Postgres with the pgvector extension (Docker: `docker run -d -p 5432:5432 \

-e POSTGRES_PASSWORD=thingery pgvector/pgvector:pg16`; Homebrew: see below)

2. apply the shipped schema (idempotent, safe to re-run):

psql "postgres://postgres:thingery@localhost:5432/postgres" \ -f node_modules/thingery/db/schema.sql

3. run it (DATABASE_URL is the only required env var):

DATABASE_URL="postgres://postgres:thingery@localhost:5432/postgres" \ PORT=3000 node node_modules/thingery/dist/index.js

The server boots at http://localhost:3000 — /mcp, /browse, /healthz, and the HTTP API. Create your account by opening /login.html — your thg_... MCP key is shown right after signup. (On the pre-fix 0.1.2 release the page 404'd — a packaging gap fixed after it; there you can still create the account through the API — the key is returned exactly once, in the signup response:)

curl -s -X POST http://localhost:3000/api/signup \

-H 'content-type: application/json' \ -d '{"email":"you@example.com","password":"at-least-8-chars"}'

→ {"seller":{"name":"you","email":"…","api_key":"thg_…"}}

Then point any MCP client at http://localhost:3000/mcp with Authorization: Bearer thg_... — or spawn it over stdio with the npx config below.

Note: the npm package publishes at release cadence and can lag main on thingery.dev

by days — /healthz reports the running version. If you need today's features,

self-host from source instead:

Self-hosted from source (development)

git clone https://github.com/thingery/thingery

cd thingery npm install docker compose up -d db # Postgres 16 + pgvector cp .env.example .env npm run db:migrate npm run db:seed # demo seller + 3 listings; prints an API key npm run dev # http://localhost:3000

No Docker? Local Postgres

npm run db:migrate needs a Postgres with the vector extension — the schema creates it unconditionally, even in keyword-only search mode. On macOS, Homebrew's pgvector bottle supports PostgreSQL 17 and 18 (not 16, the version the Docker setup uses — any of them works for Thingery):

brew install postgresql@18 pgvector

brew services start postgresql@18 psql postgres -c "CREATE ROLE thingery LOGIN PASSWORD 'thingery';" \ -c "CREATE DATABASE thingery OWNER thingery;" psql -d thingery