Etsy Marketplace

Etsy Store Query

Search Etsy stores using keyword, category, country, status, performance, and date filters.

MCP tool name

nexscope_etsy_store_query

MCP endpoint

https://api.nexscope.ai/api/skill-api/v2/mcp

JSON-RPC method

tools/call

Authentication

Use OAuth 2.1 Authorization Code with PKCE and the mcp:tools scope. API keys remain supported as a compatibility option.

Authorization: Bearer nk-xxxxxxxxxxxxxxxxx

If authentication fails, ask the user to open API Access and copy a valid key.

Call this MCP tool

Initialize an MCP 2025-11-25 Streamable HTTP session at https://api.nexscope.ai/api/skill-api/v2/mcp, then use tools/call.

{
  "jsonrpc": "2.0",
  "id": "etsy-store-query-1",
  "method": "tools/call",
  "params": {
    "name": "nexscope_etsy_store_query",
    "arguments": {
      "page": 1,
      "pageSize": 20,
      "searchKey": "Lewshop1"
    }
  }
}

MCP 2025-11-25 · Streamable HTTP

Progress is delivered on the original POST SSE response. GET SSE carries notifications; reconnecting must query existing asynchronous work rather than submit again.

Arguments

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

Any of option 1

Name	Type	Required	Description
`data`	`object`	required	Data value used by this API operation.
`data.columns`	`array`	optional	Provider rendering columns. Example: []
`data.costTime`	`integer`	optional	Execution time reported by the upstream provider. Example: null
`data.costToken`	`integer`	optional	Provider-reported token cost. Example: 3600
`data.dataSnapshotMonth`	`string`	optional	Data snapshot month returned by the upstream provider. Example: null
`data.page`	`integer`	optional	Current page 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.pageSize`	`integer`	optional	Page size returned by the upstream provider. Example: null
`data.sourceTool`	`string`	optional	Tool type: ehunt. Example: null
`data.sourceType`	`string`	optional	Source type: etsy. Example: null
`data.storeNum`	`integer`	optional	Total matching stores. Example: 1
`data.stores`	`array`	optional	Etsy stores. Example: []
`data.stores[]`	`object`	required	Etsy stores.
`data.stores[].category`	`array`	optional	Primary categories. Example: []
`data.stores[].country`	`array`	optional	Store countries or regions. Example: []
`data.stores[].favorites`	`integer`	optional	Favorite count. Example: 1
`data.stores[].favoritesWeekly`	`integer`	optional	Weekly new favorite count. Example: null
`data.stores[].isRaving`	`integer`	optional	Raving store indicator: 1 means yes. Example: null
`data.stores[].isStar`	`integer`	optional	Star store indicator: 1 means yes. Example: null
`data.stores[].logoUrl`	`string`	optional	Store avatar URL. Example: null
`data.stores[].productCount`	`integer`	optional	Store product count. Example: null
`data.stores[].rating`	`number`	optional	Store rating. Example: 4.8
`data.stores[].reviews`	`integer`	optional	Review count. Example: 1
`data.stores[].reviewsWeekly`	`integer`	optional	Weekly new review count. Example: null
`data.stores[].salesTotal`	`integer`	optional	Total sales. Example: 1
`data.stores[].salesWeekly`	`integer`	optional	Weekly sales. Example: 1
`data.stores[].shopWebsite`	`string`	optional	Store website or external link. Example: null
`data.stores[].startAt`	`string`	optional	Store opening date. Example: null
`data.stores[].status`	`integer`	optional	Store status. Example: 1
`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.title`	`string`	optional	Response title. Example: null
`data.total`	`integer`	optional	Records returned on the current page. Example: 1
`data.totalPage`	`integer`	optional	Total page count returned by the upstream provider. Example: null
`data.type`	`string`	optional	Render style. Example: null

Any of option 2

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

Examples

Example arguments

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

Example structuredContent

{
  "code": 0,
  "cost": "-1",
  "data": {
    "columns": [],
    "costToken": 3600,
    "storeNum": 1,
    "stores": [
      {
        "category": [],
        "country": [],
        "favorites": 1,
        "rating": 4.8,
        "reviews": 1,
        "salesTotal": 1,
        "salesWeekly": 1,
        "status": 1,
        "storeId": "123456",
        "storeName": "Lewshop1",
        "storeUrl": "https://www.etsy.com/shop/Lewshop1"
      }
    ],
    "total": 1
  },
  "msg": null,
  "time": "2026-01-01 00:00:00",
  "traceId": null,
  "ts": "0"
}