Etsy Marketplace

Etsy Store Query MCP Tool

Returns Etsy store profiles and marketplace performance metrics.

MCP tool name

nexscope_etsy_store_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-store-query-1",
  "method": "tools/call",
  "params": {
    "name": "nexscope_etsy_store_query",
    "arguments": {
      "pageSize": 20,
      "page": 1,
      "searchKey": "Lewshop1"
    }
  }
}

Legacy endpoint

POST /api/skill-api/v1/mcp

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

Example structuredContent

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