# Etsy Gold — MCP

> Etsy seller ops via Etsy OpenAPI v3 — 18 tools: listings CRUD, variant bulk by SKU, receipts, A-F grade + worst-first whole-shop audit, photo upload, taxonomy/tag gap, shipping, conversations, fulfillment, profit calc. + gold_setup_check =19 total. BYOK, fail-closed.

**Binary:** `etsy-gold` · **Package:** `etsy-gold` · **MCP name:** `ai.studio/etsy-gold`

> **Disclosure:** This project is an independent Gold wrapper around the public Etsy OpenAPI v3 (`https://developers.etsy.com/documentation/openapi`). We are not affiliated with Etsy, Inc. Etsy is a trademark of Etsy, Inc. This wrapper's original code is © 2026 Studio AI under `GOLD MCP — COMMERCIAL LICENSE v1.0`. Upstream docs remain under their own licenses. `THIRD_PARTY_NOTICES.md` + `upstream/ORIGINAL_LICENSE` preserve attribution.

> **BYOK + fail-closed before price:** Bring your own keys — `ETSY_ACCESS_TOKEN` + `ETSY_SHOP_ID` stay on your machine, fail-closed without them (`config_error`, no fake shop). Works only on your own shop — BYOK, no shared backend. No keys in this repo, no backend submit while staged. **Price $29 once** (no subscription) — all 18 `gold_*` tools + `gold_setup_check` =19 require `GOLD_LICENSE_KEY`, fail-closed without it (offline 7-day grace). See `src/moat.ts` + `src/shared/gold-license.ts`.

**Buy Pro — PAID ONLY $29 once via Keygen CE (no free tier):** https://gumroad.com/l/etsy-gold — staged, no live checkout.

## Quick start

```bash
npx -y etsy-gold
# or local
npm install
npm run build
node dist/index.js
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "etsy-gold": {
      "command": "npx",
      "args": ["-y", "etsy-gold"],
      "env": {
        "ETSY_ACCESS_TOKEN": "YOUR_OAUTH_TOKEN",
        "ETSY_SHOP_ID": "12345678",
        "GOLD_LICENSE_KEY": "gold_pro_..."
      }
    }
  }
}
```

## Env vars (BYOK — no fake data, fail-closed)

| Var | Purpose |
|-----|---------|
| `ETSY_ACCESS_TOKEN` | Etsy OAuth token (BYOK, from your Etsy app) |
| `ETSY_SHOP_ID` | Your Etsy shop ID (numeric) |
| `GOLD_LICENSE_KEY` / `GOLD_LICENSE` | Gold license — PAID ONLY PRO $29 once (no free tier) via Keygen CE. Or `~/.gold-mcp/license.key` |
| `KEYGEN_ACCOUNT_ID` | Keygen CE account id for online validation (offline 7-day grace) |

Without `ETSY_ACCESS_TOKEN` + `ETSY_SHOP_ID` every tool returns `config_error` (no invented shop). Without `GOLD_LICENSE_KEY` every tool throws `requires PRO license` — fail-closed.

## Tools (gold_* — 18 tools + gold_setup_check =19 total, all PRO $29 — BYOK fail-closed)

| Tool | What it does |
|------|--------------|
| `gold_etsy_create_listing` | Create listing — title/description/price/quantity/tags/materials |
| `gold_etsy_update_listing` | Update listing fields by listing_id |
| `gold_etsy_get_listing` | Get single listing with details |
| `gold_etsy_list_listings` | List active listings with pagination |
| `gold_etsy_get_inventory` | Get listing inventory — variations with price/qty/SKU |
| `gold_etsy_update_variation_price_qty` | Bulk price/qty update by SKU up to 50 (variant bulk) |
| `gold_etsy_bulk_grade_shop` | Grade whole shop A-F worst-first — the moat (eRank never built) |
| `gold_etsy_grade_listing` | A-F grade single listing vs 20-point checklist |
| `gold_etsy_profit_calculator` | True profit after Etsy fees (6.5% + payments + shipping) |
| `gold_etsy_tag_gap` | Tag gap — long-tail tag suggestions from top competitors |
| `gold_etsy_find_category` | Taxonomy category finder (Etsy taxonomy) |
| `gold_etsy_upload_listing_image` | Upload listing photo |
| `gold_etsy_shipping_profiles` | List shipping profiles |
| `gold_etsy_assign_shipping_profile` | Assign shipping profile to listing |
| `gold_etsy_conversations_list` | List Etsy conversations (read-only) |
| `gold_etsy_shop_receipts` | List receipts/orders with status |
| `gold_etsy_fulfill_order_tracking` | Add tracking/fulfillment to receipt |
| `gold_etsy_review_sync` | List reviews for shop (sync) |
| `gold_setup_check` | Preflight — verifies ETSY_ACCESS_TOKEN + ETSY_SHOP_ID + ETSY_KEYSTRING + GOLD_LICENSE_KEY fail-closed |

All 18 gold tools + `gold_setup_check` =19 total are `gold_*` prefixed — PAID ONLY PRO $29 once, BYOK fail-closed without ETSY keys and `GOLD_LICENSE_KEY` (offline 7-day grace). See `src/moat.ts` 18 tools.

## Upstream attribution

Derivative shape from Etsy OpenAPI v3 docs + eRank/Star seller patterns (no code copied, API only). Original code © 2026 Studio AI under `GOLD MCP — COMMERCIAL LICENSE v1.0 (2026-08-19)` — see `LICENSE` — `LICENSE TIERS: PRO $29 once (PAID ONLY, no free tier) | TEAM $99/mo` via Keygen CE. Etsy API docs: https://developers.etsy.com/documentation/reference

## Weekly watch list

Etsy official dev-mcp is docs-only (no ops) — window OPEN but closing. Monthly wayback diff on dev-mcp tool count. Registry-listed via `smithery.yaml` + `mcp.json` (Glama / Pulsemcp / mcp.so / mcp-registry).

## License

`LICENSE` — PRO $29 once, TEAM $99/mo. Etsy trademark remains Etsy's. No affiliation.

## See also

- Master plan: `docs/MCP-GOLD-MASTER-PLAN-2026-08-19.md`
- Third-party notices: `THIRD_PARTY_NOTICES.md`
- Etsy docs: https://developers.etsy.com/documentation/reference