Etsy Marketplace

Etsy Store Query MCP Tool

Returns Etsy store profiles and marketplace performance metrics.

MCP tool name

nexscope_etsy_store_query

Equivalent REST API path

https://api.nexscope.ai/api/skill-api/v1/skills/etsy-store-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-store-query-1",
  "method": "tools/call",
  "params": {
    "name": "nexscope_etsy_store_query",
    "arguments": {
      "page": 1,
      "pageSize": 20,
      "searchKey": "Lewshop1"
    }
  }
}

REST API equivalent

POST https://api.nexscope.ai/api/skill-api/v1/skills/etsy-store-query/run

Canonical detail URL

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

Arguments

Name	Type	Required	Meaning
`searchKey`	`string`	optional	Store name, keyword, or Etsy store URL. Example: Lewshop1
`category`	`string`	optional	Primary store category. Example: Jewelry
`country`	`string`	optional	Store country or region. Example: US
`status`	`integer`	optional	Store status: 1 active, 0 inactive. Example: 1
`isRaving`	`integer`	optional	Raving store flag: 1 yes. Example: 1
`isStar`	`integer`	optional	Star store flag: 1 yes. Example: 1
`beginFavorites`	`integer`	optional	Minimum total favorites. Example: 0
`endFavorites`	`integer`	optional	Maximum total favorites. Example: 10000
`beginFavoritesWeekly`	`integer`	optional	Minimum weekly favorites. Example: 0
`endFavoritesWeekly`	`integer`	optional	Maximum weekly favorites. Example: 1000
`beginReviews`	`integer`	optional	Minimum total reviews. Example: 0
`endReviews`	`integer`	optional	Maximum total reviews. Example: 10000
`beginReviewsWeekly`	`integer`	optional	Minimum weekly reviews. Example: 0
`endReviewsWeekly`	`integer`	optional	Maximum weekly reviews. Example: 1000
`beginSales`	`integer`	optional	Minimum total sales. Example: 0
`endSales`	`integer`	optional	Maximum total sales. Example: 100000
`beginSalesWeekly`	`integer`	optional	Minimum weekly sales. Example: 0
`endSalesWeekly`	`integer`	optional	Maximum weekly sales. Example: 1000
`beginStoreOpenedAt`	`string`	optional	Opening date range start in YYYY-MM-DD format. Example: 2020-01-01
`endStoreOpenedAt`	`string`	optional	Opening date range end in YYYY-MM-DD format. Example: 2026-01-01
`sortBy`	`integer`	optional	Sort field: 8 total sales, 9 weekly sales, 10 reviews, 11 favorites. Example: 8
`sortDesc`	`integer`	optional	Sort direction: 1 descending, 0 ascending. Example: 1
`page`	`integer`	optional	Page number starting from 1. Example: 1
`pageSize`	`integer`	optional	Items per page from 1 to 100. Example: 20

Response fields

Treat structuredContent as the programmatic API response payload.

Name	Type	Required	Meaning
`total`	`integer`	optional	Records returned on the current page. Example: 1
`storeNum`	`integer`	optional	Total matching stores. Example: 1
`stores`	`array`	optional	Etsy stores. Example: []
`stores[].storeId`	`string`	optional	Store identifier. Example: 123456
`stores[].storeName`	`string`	optional	Store name. Example: Lewshop1
`stores[].storeUrl`	`string`	optional	Etsy store URL. Example: https://www.etsy.com/shop/Lewshop1
`stores[].country`	`array`	optional	Store countries or regions. Example: []
`stores[].category`	`array`	optional	Primary categories. Example: []
`stores[].salesTotal`	`integer`	optional	Total sales. Example: 1
`stores[].salesWeekly`	`integer`	optional	Weekly sales. Example: 1
`stores[].reviews`	`integer`	optional	Review count. Example: 1
`stores[].favorites`	`integer`	optional	Favorite count. Example: 1
`stores[].rating`	`number`	optional	Store rating. Example: 4.8
`stores[].status`	`integer`	optional	Store status. Example: 1
`columns`	`array`	optional	Provider rendering columns. Example: []
`costToken`	`integer`	optional	Provider-reported token cost. Example: 3600
`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: {}
`type`	`string`	optional	Provider-specific render or payload type. Example: {}
`title`	`string`	optional	Provider-specific response title. Example: {}
`sourceType`	`string`	optional	Provider-specific source platform type. Example: {}
`sourceTool`	`string`	optional	Provider-specific source tool name. 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

{
  "page": 1,
  "pageSize": 20,
  "searchKey": "Lewshop1"
}

Example structuredContent

{
  "total": 1,
  "storeNum": 1,
  "stores": [
    {
      "storeId": "123456",
      "storeName": "Lewshop1",
      "storeUrl": "https://www.etsy.com/shop/Lewshop1",
      "country": [],
      "category": [],
      "salesTotal": 1,
      "salesWeekly": 1,
      "reviews": 1,
      "favorites": 1,
      "rating": 4.8,
      "status": 1
    }
  ],
  "columns": [],
  "costToken": 3600
}