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

Legacy MCP endpoint

/api/skill-api/v1/mcp

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,
      "page": 1,
      "searchKey": "phone case"
    }
  }
}

Legacy endpoint

POST /api/skill-api/v1/mcp

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	Description
`data`	`any`	required	Data value used by this API operation.
`code`	`integer`	required	0 means accepted or successful; nonzero is a platform error.
`msg`	`string \| null`	required	Msg value used by this API operation.
`ts`	`string`	required	Epoch milliseconds.
`time`	`string`	required	Server local time: yyyy-MM-dd HH:mm:ss.
`cost`	`string`	required	Elapsed milliseconds, never credits; -1 outside web requests.
`traceId`	`string \| null`	required	Trace id value used by this API operation.

Any of option 1

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

Any of option 2

Name	Type	Required	Description
`data`	`null`	required	Data value used by this API operation.

Examples

Example arguments

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

Example structuredContent

{
  "data": {
    "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
      }
    ]
  },
  "code": 0,
  "msg": null,
  "ts": "0",
  "time": "2026-01-01 00:00:00",
  "cost": "-1",
  "traceId": null
}