Skip to main content
Glama
etsy-seller-mcp

etsy-seller-mcp

by mrsxs

etsy-seller-mcp

Etsy 卖家 MCP(stdio,零依赖,Node ≥ 22):

  • Etsy Open API v3 全部 107 个接口:目录搜索(中英文关键词)→ 看参数 → 调用,参数按官方规格校验。

  • 组合工具:店铺概况、商品列表、商品详情、规格库存、订单汇总、支付流水、评价、前台竞品搜索、类目搜索,一次调用出结果。

  • 写接口(42 个)一律两步:etsy_write_preview 预检(读改前状态,给出改前 → 改后、费用和风险提示,不改平台上的东西)→ 用户确认 → etsy_write_apply 执行。执行前重新读一遍,被别处改过就拒绝;网络中断后同一个 preview_id 再执行会先对账。

  • 多店铺:每家店对应一个 HubStudio 浏览器环境,授权在这家店自己的环境(IP、指纹)里完成;每家店用自己的 Seller app。

  • 隐私:结果里买家姓名、地址、邮箱、留言、礼物附言、个性化内容一律隐藏,只留收货国家。

工具

工具

做什么

etsy_shops

已配置的店铺、授权状态和有效期、是否只读

etsy_shop_overview

店铺概况 + 分区、运费模板、退货政策

etsy_listings

商品列表(在售 / 下架 / 售罄 / 草稿 / 过期),可按标题 / 标签 / SKU 查找

etsy_listing_detail

单个商品全部信息 + 每个规格的 SKU、价格、数量

etsy_inventory

批量查规格库存(最多 100 个商品)

etsy_orders

最近 N 天订单:按币种汇总、已付款 / 发货 / 取消、热卖商品、每单明细

etsy_finance

支付账户流水:余额、各类收支、净额、最近 20 笔

etsy_reviews

评价:平均分、星级分布、差评原文

etsy_market_search

前台在售商品搜索(竞品价格分布,统一换算成美元等)

etsy_category_search

卖家类目搜索(刊登用叶子类目)

etsy_api_catalog / etsy_api_describe / etsy_api_call

全部接口:搜索 → 看参数 → 调查询接口

etsy_write_preview / etsy_write_apply

任意写接口:预检 → 确认后执行

Related MCP server: Etsy MCP Server

第一次用:每家店做一次

  1. 建 Seller app:在这家店的 HubStudio 环境里登录 Etsy,打开 https://www.etsy.com/developers/your-apps → Create a seller app,等批准(通常很快)。Seller app 只能授权建它的那个账号自己的店,所以每家店各建一个。

  2. 登记回调地址:Your Apps → Edit callback URLs,加上 https://localhost/etsy-seller-mcp/callback (授权时回跳请求会在浏览器里直接被拦下取 code,不需要真有这个网址。)

  3. 授权(先开小火箭等代理,HubStudio 环境代理才连得上):

    npx -y etsy-seller-mcp@latest auth --container <HubStudio 环境 ID>

    会在这家店的 HubStudio 浏览器里新开标签页打开 Etsy 授权页,点「Grant access」即可。这家店还没有应用密钥时,会先从它环境里的 Your Apps 页读取(不在终端显示)。授权 90 天有效,期间用工具会自动续期;超过 90 天没用就要重新授权。

    • --app-from-page:重新读取应用密钥(换了应用、轮换了 shared secret 时)

    • --read-only:只申请读权限

    • --redirect-uri <URL>:回调地址换成别的(要和登记的完全一致)

HubStudio 环境 ID 在 HubStudio 环境列表里(或本地接口 POST http://127.0.0.1:6873/api/v1/env/list)。

MCP 配置

{
  "mcpServers": {
    "etsy-seller": {
      "command": "npx",
      "args": ["-y", "etsy-seller-mcp@latest"],
      "env": {
        "ETSY_SHOPS": "[{\"name\":\"美国店\",\"container_code\":\"1111111111\",\"default\":true},{\"name\":\"二店\",\"container_code\":\"2222222222\"}]"
      }
    }
  }
}

问到某家店时传 shop(店铺名或环境 ID);不传用默认店。不设 ETSY_SHOPS 时,自动用密钥文件里已授权的店。

环境变量

说明

ETSY_SHOPS

店铺数组:name、container_code(HubStudio 环境 ID)、default

ETSY_CONTAINER_CODE

只有一家店时可以只写环境 ID

ETSY_API_KEYS

应用密钥和店铺授权文件,默认 ~/.config/etsy-seller-mcp/api-keys.json(600 权限,换电脑时原样拷过去)

ETSY_DATA_DIR

预检记录、执行日志(write-log.jsonl)、锁,默认 ~/.etsy-seller-mcp

ETSY_READ_ONLY

true = 只读,不允许任何写操作

HUBSTUDIO_API

HubStudio 本地接口,默认 http://127.0.0.1:6873(只有 auth 用)

注意

  • 额度:每个应用 10 次 / 秒、1 万次 / 天(Etsy 后台可看)。本工具每进程限 5 次 / 秒;遇到限流会说明,不会反复重试。

  • 分页:每页最多 100 条,offset 最大 12000。

  • 费用:草稿发布 / 商品从下架、过期改成在售时 Etsy 收 0.20 美元刊登费,预检会提示。

  • 库存 / 价格 / 规格(updateListingInventory)是整组替换;Etsy 现在要求每个 offering 带 readiness_state_id(处理时间配置,getShopReadinessStateDefinitions 查)。

  • 结果不确定时:修改 / 删除类用同一个 preview_id 再执行会先对账、可安全重发;创建 / 上传 / 加运单类不会自动重发,要先查询确认。

  • 账本金额按最小货币单位记,etsy_finance 已除以 100。

  • 调 Etsy 接口走本机网络(Node 不读系统代理);HubStudio 只在授权时用。

  • 接口目录来自官方 OpenAPI(spec/etsy-oas-3.0.0.json),更新:下载新版覆盖后 npm run build-spec。

开发

npm test
node bin/etsy-seller-mcp.mjs --help

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables seamless integration with Etsy's marketplace API v3 to search listings, manage shop inventory, create and update products, optimize SEO, and access seller resources with OAuth support for authenticated operations.
      5
      -
    • A
      license
      B
      quality
      D
      maintenance
      Provides full access to the Etsy Open API v3 for both buyer browsing and seller shop management through 37 specialized tools. It enables users to manage listings, process orders, handle shipping, and access inventory data via secure OAuth 2.0 authentication.
      41
      13
      MIT
    • F
      license
      B
      quality
      C
      maintenance
      Enables Etsy sellers to manage their shops via natural language, including listing CRUD, bulk price and quantity updates by SKU, whole-shop A-F grade audits, photo uploads, shipping profiles, conversations, receipts, fulfillment tracking, and profit calculation.
      19
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Wraps the Etsy Open API v3 in pure capability primitives so AI agents can read and manage shops, listings, images, inventory, translations, digital files, receipts, payments, shipping profiles, taxonomy, reviews, users and buyer addresses, plus bulk listing and alt-text updates. It contains no baked-in scoring, SEO or tag-generation heuristics, leaving all judgment to the calling model.
      MIT