# thingery [Health: Active]

**Category:** 🛒 E-Commerce  
**Repository:** https://github.com/thingery/thingery  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/thingery

## Description
Open item database and MCP server for AI agents to list, find, and trade second-hand goods.

## Tools
Capabilities this server exposes over MCP:

- **describe_category** — List categories and their declared attribute fields — the self-describing schema for agents. Declared fields get validated on create; undeclared keys are allowed, searchable, and their real use is surfaced via `undeclared_in_use
- **search_items** — Hybrid semantic + keyword search with price/category/condition/attribute filters (any attribute key, declared or not)
- **get_item** — Fetch one listing by id
- **create_listing** — Publish an item — core fields plus a flexible `attributes` object (declared keys validated, extras pass through and stay searchable)
- **add_item_image** — Attach a photo to a listing (base64 in, stored server-side — no URLs needed; max 5 MB decoded). Images are re-encoded at ingest: metadata (EXIF/GPS/XMP) stripped, downscaled to ≤ 2000 px, animated GIFs stored as stills; large PNGs may be rejected — prefer JPEG
- **my_listings** — Your listings by status
- **update_listing** — Mark reserved/sold, adjust price, edit text or attributes
- **get_payout_setup** — Stripe Express onboarding URL + status — optional, enables platform payment
- **create_order** — Order an item — returns a Stripe Checkout URL (stripe mode) or tracks an off-platform order
- **get_order** — One of your orders (buyer or seller side): status, tracking, deadlines
- **cancel_order** — Cancel while cancellable; paid orders refund instead
- **record_tracking** — Record carrier + tracking code; auto carrier tracker when EasyPost is configured
- **confirm_payment** — Confirm an off-platform payment (pending → sold)
- **confirm_receipt** — Confirm delivery — dispute window opens
- **open_dispute** — Dispute a delivered order; seller payout is held
- **release_funds** — Waive the dispute window, release the seller's payout now

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "thingery": {
    "command": "npx",
    "args": ["-y","thingery"],
    "env": {
      "DATABASE_URL": ""
    }
  }
}
```

**Requires environment variables:** `DATABASE_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What thingery does

The thingery MCP server exposes an open item database for second-hand goods through MCP tools. Agents can inspect category schemas, search listings, retrieve individual items, create listings, attach images, and manage listing status, prices, text, and attributes. Anonymous users can use the public read operations, while publishing and account-specific actions require seller or account authentication.

Its flexible listing model supports core item fields plus an `attributes` object. Category-declared attributes are validated during creation, but undeclared keys are also retained and searchable. This makes the thingery MCP server suitable for varied goods where every category does not share the same specification fields. The service belongs in the 🛒 E-Commerce category and can support workflows such as finding a used camera within a price limit or turning an item description into a marketplace listing.

## How it works

Search uses hybrid semantic and keyword matching and accepts filters for price, category, condition, and arbitrary attributes. Embeddings are optional: with an OpenAI-compatible embedding endpoint configured, semantic search can be used; without an embedding key, the deployment can operate in keyword-only mode.

Orders can run in Stripe mode when the deployment has Stripe configured and the seller completes Stripe Express payout onboarding. In that mode, the platform charges the buyer, holds funds, and pays the seller after delivery and the dispute period. Without those requirements, the server records an off-platform order while the parties handle payment themselves. Tools cover order creation, status lookup, cancellation, tracking, payment confirmation, receipt confirmation, disputes, and fund release.

Images are submitted as base64 data and stored by the server, so listings do not need externally hosted image URLs. Ingest processing removes EXIF, GPS, and XMP metadata, limits dimensions to 2,000 pixels, and stores animated GIFs as still images. Decoded uploads are limited to 5 MB, and large PNG files may be rejected.

## Setup and configuration

Self-hosting requires Node 20, Postgres, and the `vector` extension. The repository quickstart installs dependencies, starts the Postgres 16 and pgvector database with Docker Compose, copies `.env.example` to `.env`, runs migrations, seeds demo data, and starts the development server. A compatible local PostgreSQL installation can also be used if the vector extension is created before migration.

The HTTP MCP endpoint is `/mcp`. MCP clients can connect to a deployment using OAuth, where supported, or a static `thg_...` bearer API key. OAuth can be disabled with `OAUTH_DISABLED=1`. For local use, the `thingery` package can run over stdio through `npx`; setting `THINGERY_API_KEY` enables authenticated operations, while omitting it leaves the process read-only.

Important configuration includes `DATABASE_URL`, the HTTP `PORT`, and `PUBLIC_BASE_URL`. `EMBED_API_URL`, `EMBED_API_KEY`, and `EMBED_MODEL` configure optional embeddings. Stripe uses `STRIPE_SECRET_KEY` and `STRIPE_WEBHOOK_SECRET`; EasyPost tracking uses its corresponding API and webhook variables. The deployment also exposes tunable order deadlines and abuse limits through environment settings.

## Tools and capabilities

The thingery MCP server provides these capabilities:

- Describe categories and their declared fields with `describe_category`.
- Search listings with `search_items` using text, price, condition, category, and attribute filters.
- Read, create, update, and organize listings with `get_item`, `create_listing`, `update_listing`, and `my_listings`.
- Add processed listing photos with `add_item_image`.
- Configure seller payouts and place or inspect orders with `get_payout_setup`, `create_order`, and `get_order`.
- Manage fulfillment and resolution with `cancel_order`, `record_tracking`, `confirm_payment`, `confirm_receipt`, `open_dispute`, and `release_funds`.

The thingery MCP server is a fit for agent-led resale flows, catalog search, and marketplace order coordination. It is less appropriate when a deployment needs a conventional fixed-schema catalog, because undeclared attributes are intentionally supported and remain part of the searchable data model.

_Full upstream README: https://allmcps.com/mcp/thingery/readme_