{
  "markdown": "# @pipeworx/etsy\n\nSearch active Etsy listings via the Etsy Open API v3 — scoped to the three\nendpoints that authenticate with just an API key (no OAuth user token).\n\nPart of [Pipeworx](https://pipeworx.io) — an MCP gateway connecting AI agents to 1558+ live data sources.\n\n## Tools\n\n- `etsy_search_listings(keywords?, limit?, offset?, sort_on?, sort_order?, min_price?, max_price?, taxonomy_id?, buyer_country?)`\n  — site-wide active-listing search (`findAllListingsActive`).\n- `etsy_search_shop_listings(shop_id, keywords?, limit?, offset?, sort_on?, sort_order?)`\n  — active listings within one shop (`findAllActiveListingsByShop`).\n- `etsy_get_listing(listing_id)` — one listing by ID (`getListing`).\n\nNo sold-price / comps data — Etsy's v3 API has none. Active listings only.\n\n## Auth\n\nBYO key only (`_apiKey`), requires an API key. Register a free app at\n<https://www.etsy.com/developers/register> to get a keystring + shared\nsecret. Pass `?_apiKey=<keystring>`; the colon-joined\n`<keystring>:<shared_secret>` form your \"Your Apps\" page displays is accepted\ntoo, and the pack handles the difference for you (see the trap below).\n\nEtsy's v3 reference marks each endpoint's required auth. Only the three\nendpoints above are `api_key`-only; everything else (shop/receipt/user\nmanagement, listing writes) requires an OAuth user token issued through\nEtsy's manual commercial-review flow — out of scope for this pack. If Etsy's\nreview later grants broader access, extend this pack rather than building a\nsecond one.\n\nRegistering an Etsy developer account requires signing in with (or creating)\nan Etsy account and a password — a human step this pack's author cannot\nperform on Bruce's behalf. See the open Needs Bruce item for platform-key\nregistration; this pack ships BYOK-gated in the meantime and its own live\ncall has not yet been verified against a real key.\n\n## Data sources\n\n- <https://developers.etsy.com/documentation/reference/> — Etsy Open API v3.\n  Base URL `https://openapi.etsy.com/v3/application`.\n\nTraps for the next person:\n\n- **Etsy contradicts itself about the `x-api-key` header value, and you\n  cannot resolve it by experiment.** The api_key reference for these three\n  endpoints documents the bare keystring; the quickstart shows the\n  colon-joined `keystring:shared_secret` pair (which is really the Basic-auth\n  credential for the OAuth token endpoint). An app awaiting Etsy's Personal\n  Approval returns a 403 that is *byte-identical* to the 403 a fabricated key\n  returns — verified with a negative control on 2026-09-09 (fleet #1279) —\n  so no probe before activation can tell the two header forms apart. The pack\n  therefore sends the keystring and, only on a 403, retries once with the raw\n  value the caller passed. Don't \"simplify\" that back to one call until a live\n  successful response says which form won.\n- This pack returns Etsy's response JSON close to verbatim (`count` +\n  `results` plus a `source` field) rather than re-mapping field names, since\n  the exact Listing resource shape was only checked against the published\n  OpenAPI reference, not a live authenticated response (no working key was\n  available at build time — see Auth above).\n\n## Quick Start\n\nAdd to your MCP client (Claude Desktop, Cursor, Windsurf, etc.):\n\n```json\n{\n  \"mcpServers\": {\n    \"etsy\": {\n      \"url\": \"https://gateway.pipeworx.io/etsy/mcp\"\n    }\n  }\n}\n```\n\n### What this endpoint actually serves\n\n`tools/list` at `https://gateway.pipeworx.io/etsy/mcp` returns the tools in the table\nabove **plus the shared Pipeworx meta-tools** — `ask_pipeworx`,\n`discover_tools`, `search_within`, `remember`/`recall` and the rest of the\ngateway-wide set. So the tool count you see is larger than this table: a\nsingle-pack endpoint currently lists roughly 30 shared tools alongside the\npack's own. The connection's `initialize` response states its exact scope, and\nis the authoritative answer for a given day.\n\nThis is deliberate, not multiplexing by accident. The meta-tools are what let a\nscoped connection answer a question this pack does not cover — via\n`ask_pipeworx`, which routes across the whole catalog — without you adding a\nsecond MCP server. There is currently no way to mount a pack endpoint without\nthem; if the extra schemas cost you more context than the routing is worth,\nconnect to the full gateway once rather than to several pack endpoints.\n\nOr connect to the full Pipeworx gateway to get every pack's tools listed\ndirectly, instead of just this one's:\n\n```json\n{\n  \"mcpServers\": {\n    \"pipeworx\": {\n      \"url\": \"https://gateway.pipeworx.io/mcp\"\n    }\n  }\n}\n```\n\nBoth URLs reach the same gateway and the same 1558+ data sources. The\nonly difference is which pack's tools are listed **directly**; `ask_pipeworx`\nreaches all of them from either one.\n\n## Standalone (no gateway account)\n\nThis package also runs as a local stdio MCP server — no Pipeworx account, no\ngateway round-trip:\n\n```json\n{\n  \"mcpServers\": {\n    \"etsy\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@pipeworx/mcp-etsy\"]\n    }\n  }\n}\n```\n\nOr run it directly to confirm it starts:\n\n```bash\nnpx -y @pipeworx/mcp-etsy\n```\n\nIt speaks MCP over stdin/stdout and answers `initialize`/`tools/list`/`tools/call`\nfor **only** this pack's tools — none of the shared meta-tools the gateway\nconnection above adds. Same source, same tools, no ask_pipeworx routing.\n\n## Using with ask_pipeworx\n\nInstead of calling tools directly, you can ask questions in plain English —\nthis works on the pack endpoint above as well as on the full gateway:\n\n```\nask_pipeworx({ question: \"your question about Etsy data\" })\n```\n\nThe gateway picks the right tool and fills the arguments automatically.\n\n## More\n\n- [Docs and guides](https://pipeworx.io/docs)\n- [pipeworx.io](https://pipeworx.io)\n\n## License\n\nMIT\n",
  "bytes": 5772,
  "sha": "ea2802aa83401aeeb7c48d87df96aaced477d9fb6506a2ae801fe4c1a396d088",
  "repo_slug": "pipeworx-io/mcp-etsy",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_pipeworx_io_etsy_6cf7ff83/readme"
}