Etsy Marketplace

Etsy Product Query MCP Tool

Query Etsy products with multi-dimensional filters (keyword/URL, price, sales, favorites, reviews, listing date, category, handmade/vintage types, Pick/Bestseller/Raving tags).

MCP tool name

nexscope_etsy_product_query

Equivalent REST API path

https://claw-callback.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/run

JSON-RPC method

tools/call

Authentication

Send the user API key as a bearer token on every MCP JSON-RPC request.

Authorization: Bearer nk_xxxxxxxxxxxxxxxxx

If authentication is missing or invalid, ask the user to open API Access and copy a valid key before calling this tool.

Call this MCP tool

Use tools/call with the MCP tool name below. The arguments object should match the table on this page.

{
  "jsonrpc": "2.0",
  "id": "etsy-product-query-1",
  "method": "tools/call",
  "params": {
    "name": "nexscope_etsy_product_query",
    "arguments": {
      "pageSize": 10,
      "searchKey": "phone case",
      "page": 1
    }
  }
}

REST API equivalent

POST /api/skill-api/v1/runhttps://claw-callback.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/run

Canonical detail URL

https://www.nexscope.ai/mcp-map/etsy-product-query

Arguments

Name	Type	Required	Meaning
`beginFavorites`	`integer`	optional	Favorite count (start), combined with end value to form the upstream favorites range Example: 1
`beginFavoritesWeekly`	`integer`	optional	Weekly new favorites (start), combined with end value to form the upstream favorites_weekly range Example: 1
`beginPrice`	`number`	optional	Price (start), combined with end price to form the upstream price range (e.g., 20~100). When only one side is provided, the upstream returns start~ or ~end Example: 1
`beginReviews`	`integer`	optional	Review count (start), combined with end value to form the upstream reviews range Example: 1
`beginReviewsWeekly`	`integer`	optional	Weekly new reviews (start), combined with end value to form the upstream reviews_weekly range Example: 1
`beginSales`	`integer`	optional	Total sales (start), combined with end value to form the upstream sales range Example: 1
`beginSalesWeekly`	`integer`	optional	Weekly sales (start), combined with end value to form the upstream sales_weekly range (e.g., 1~100) Example: 1
`category`	`string`	optional	Product category ID (single category), see the Category Query API Example: {}
`country`	`string`	optional	Shipping country Example: {}
`currencyCode`	`string`	optional	Currency code Example: {}
`endFavorites`	`integer`	optional	Favorite count (end) Example: 1
`endFavoritesWeekly`	`integer`	optional	Weekly new favorites (end) Example: 1
`endPrice`	`number`	optional	Price (end), combined with start price to form the upstream price range Example: 1
`endReviews`	`integer`	optional	Review count (end) Example: 1
`endReviewsWeekly`	`integer`	optional	Weekly new reviews (end) Example: 1
`endSales`	`integer`	optional	Total sales (end) Example: 1
`endSalesWeekly`	`integer`	optional	Weekly sales (end) Example: 1
`isBestsell`	`integer`	optional	Whether the product is a bestseller Example: 1
`isPick`	`integer`	optional	Whether the product is a Pick item Example: 1
`isRaving`	`integer`	optional	Whether the product is a Raving item Example: 1
`listedTime`	`string`	optional	Listing time no earlier than this date (YYYY-MM-DD) Example: {}
`page`	`integer`	optional	Page number (starting from 1) Example: 1
`pageSize`	`integer`	optional	Items per page, max 100, recommended not to exceed 50 Example: 10
`productType`	`string`	optional	Product type, comma-separated for multiple: 1=Handmade 2=Vintage 3=Digital 4=Custom 9=Other Example: {}
`searchKey`	`string`	optional	Search keyword or Etsy product URL Example: {}
`sortBy`	`integer`	optional	Sort field (corresponds to upstream sort_by, values 1~6) Example: 1
`sortDesc`	`integer`	optional	Sort direction (corresponds to upstream desc). Schema example: descending 1, ascending 2 (encoding differs from store query's sortDesc) Example: 1
`status`	`integer`	optional	Product status (example: 1=active, 0=inactive) Example: 1

Response fields

Treat structuredContent as the programmatic API response payload.

Name	Type	Required	Meaning
`total`	`integer`	optional	Record count (number of records returned on this page, for alignment with list length) Example: 1
`sourceTool`	`string`	optional	Tool type: ehunt Example: {}
`sourceType`	`string`	optional	Source type: etsy Example: {}
`columns`	`array`	optional	Rendered columns Example: []
`costToken`	`integer`	optional	Token consumption (estimated based on records returned on this page) Example: 1
`productNum`	`integer`	optional	Total number of matching products (upstream product_num) Example: 1
`title`	`string`	optional	Title Example: {}
`type`	`string`	optional	Render style Example: {}
`products`	`array`	optional	Etsy product list Example: []
`products[].category`	`string`	optional	Category name Example: {}
`products[].favorites`	`integer`	optional	Favorite count Example: 1
`products[].favoritesWeekly`	`integer`	optional	Weekly new favorites Example: 1
`products[].imageUrl`	`string`	optional	Main image URL Example: https://example.com/image.jpg
`products[].isBestsell`	`integer`	optional	Whether bestseller: 1=Yes Example: 1
`products[].isPick`	`integer`	optional	Whether Pick: 1=Yes Example: 1
`products[].isRaving`	`integer`	optional	Whether Raving: 1=Yes Example: 1
`products[].price`	`number`	optional	Price Example: 1
`products[].productUrl`	`string`	optional	Product link Example: https://example.com/image.jpg
`products[].releaseTime`	`string`	optional	Listing/release time Example: {}
`products[].reviews`	`integer`	optional	Review count Example: 1
`products[].reviewsWeekly`	`integer`	optional	Weekly new reviews Example: 1
`products[].salesTotal`	`integer`	optional	Total sales Example: 1
`products[].salesWeekly`	`integer`	optional	Weekly sales Example: 1
`products[].shipsFrom`	`string`	optional	Shipping country Example: {}
`products[].status`	`integer`	optional	Product status: 1=active, 0=inactive Example: 1
`products[].storeName`	`string`	optional	Store name Example: {}
`products[].tags`	`string`	optional	Tags Example: {}
`products[].title`	`string`	optional	Product title Example: {}
`errcode`	`integer`	optional	Upstream status code returned by the provider. Example: {}
`errmsg`	`string`	optional	Upstream status message returned by the provider. Example: {}
`code`	`string`	optional	Provider-specific status code. Example: {}
`msg`	`string`	optional	Provider-specific status message. Example: {}
`message`	`string`	optional	Provider-specific message. Example: {}
`costTime`	`integer`	optional	Execution time reported by the upstream provider. Example: {}
`page`	`integer`	optional	Current page returned by the upstream provider. Example: {}
`pageSize`	`integer`	optional	Page size returned by the upstream provider. Example: {}
`pageItemCount`	`integer`	optional	Item count on the current page returned by the upstream provider. Example: {}
`totalPage`	`integer`	optional	Total page count returned by the upstream provider. Example: {}
`dataSnapshotMonth`	`string`	optional	Data snapshot month returned by the upstream provider. Example: {}

Examples

Example arguments

{
  "pageSize": 10,
  "searchKey": "phone case",
  "page": 1
}

Example structuredContent

{
  "total": 1,
  "columns": [],
  "costToken": 1,
  "productNum": 1,
  "products": [
    {
      "favorites": 1,
      "favoritesWeekly": 1,
      "imageUrl": "https://example.com/image.jpg",
      "isBestsell": 1,
      "isPick": 1,
      "isRaving": 1,
      "price": 1,
      "productUrl": "https://example.com/image.jpg",
      "reviews": 1,
      "reviewsWeekly": 1,
      "salesTotal": 1,
      "salesWeekly": 1,
      "status": 1
    }
  ]
}