Skip to content
Back to search

etsy-seller-mcp

Etsy seller MCP server: all 107 Etsy Open API v3 endpoints, one-call shop/listing/order/finance tools, preview → confirm → apply for every write, multi-shop via HubStudio.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mrsxs--etsy-seller-mcp/badge.svg)](/listings/mrsxs--etsy-seller-mcp)

HTML

<a href="/listings/mrsxs--etsy-seller-mcp"><img src="/api/listings/mrsxs--etsy-seller-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 91 lines
  1. # etsy-seller-mcp
  2. Etsy 卖家 MCP(stdio,零依赖,Node ≥ 22):
  3. - **Etsy Open API v3 全部 107 个接口**:目录搜索(中英文关键词)→ 看参数 → 调用,参数按官方规格校验。
  4. - **组合工具**:店铺概况、商品列表、商品详情、规格库存、订单汇总、支付流水、评价、前台竞品搜索、类目搜索,一次调用出结果。
  5. - **写接口(42 个)一律两步**:`etsy_write_preview` 预检(读改前状态,给出改前 → 改后、费用和风险提示,不改平台上的东西)→ 用户确认 → `etsy_write_apply` 执行。执行前重新读一遍,被别处改过就拒绝;网络中断后同一个 `preview_id` 再执行会先对账。
  6. - **多店铺**:每家店对应一个 HubStudio 浏览器环境,授权在这家店自己的环境(IP、指纹)里完成;每家店用自己的 Seller app。
  7. - **隐私**:结果里买家姓名、地址、邮箱、留言、礼物附言、个性化内容一律隐藏,只留收货国家。
  8. ## 工具
  9. | 工具 | 做什么 |
  10. |---|---|
  11. | `etsy_shops` | 已配置的店铺、授权状态和有效期、是否只读 |
  12. | `etsy_shop_overview` | 店铺概况 + 分区、运费模板、退货政策 |
  13. | `etsy_listings` | 商品列表(在售 / 下架 / 售罄 / 草稿 / 过期),可按标题 / 标签 / SKU 查找 |
  14. | `etsy_listing_detail` | 单个商品全部信息 + 每个规格的 SKU、价格、数量 |
  15. | `etsy_inventory` | 批量查规格库存(最多 100 个商品) |
  16. | `etsy_orders` | 最近 N 天订单:按币种汇总、已付款 / 发货 / 取消、热卖商品、每单明细 |
  17. | `etsy_finance` | 支付账户流水:余额、各类收支、净额、最近 20 笔 |
  18. | `etsy_reviews` | 评价:平均分、星级分布、差评原文 |
  19. | `etsy_market_search` | 前台在售商品搜索(竞品价格分布,统一换算成美元等) |
  20. | `etsy_category_search` | 卖家类目搜索(刊登用叶子类目) |
  21. | `etsy_api_catalog` / `etsy_api_describe` / `etsy_api_call` | 全部接口:搜索 → 看参数 → 调查询接口 |
  22. | `etsy_write_preview` / `etsy_write_apply` | 任意写接口:预检 → 确认后执行 |
  23. ## 第一次用:每家店做一次
  24. 1. **建 Seller app**:在这家店的 HubStudio 环境里登录 Etsy,打开 <https://www.etsy.com/developers/your-apps> → Create a seller app,等批准(通常很快)。Seller app 只能授权建它的那个账号自己的店,所以**每家店各建一个**。
  25. 2. **登记回调地址**:Your Apps → Edit callback URLs,加上
  26. `https://localhost/etsy-seller-mcp/callback`
  27. (授权时回跳请求会在浏览器里直接被拦下取 code,不需要真有这个网址。)
  28. 3. **授权**(先开小火箭等代理,HubStudio 环境代理才连得上):
  29. ```bash
  30. npx -y etsy-seller-mcp@latest auth --container <HubStudio 环境 ID>
  31. ```
  32. 会在这家店的 HubStudio 浏览器里新开标签页打开 Etsy 授权页,点「Grant access」即可。这家店还没有应用密钥时,会先从它环境里的 Your Apps 页读取(不在终端显示)。授权 90 天有效,期间用工具会自动续期;超过 90 天没用就要重新授权。
  33. - `--app-from-page`:重新读取应用密钥(换了应用、轮换了 shared secret 时)
  34. - `--read-only`:只申请读权限
  35. - `--redirect-uri <URL>`:回调地址换成别的(要和登记的完全一致)
  36. HubStudio 环境 ID 在 HubStudio 环境列表里(或本地接口 `POST http://127.0.0.1:6873/api/v1/env/list`)。
  37. ## MCP 配置
  38. ```json
  39. {
  40. "mcpServers": {
  41. "etsy-seller": {
  42. "command": "npx",
  43. "args": ["-y", "etsy-seller-mcp@latest"],
  44. "env": {
  45. "ETSY_SHOPS": "[{\"name\":\"美国店\",\"container_code\":\"1111111111\",\"default\":true},{\"name\":\"二店\",\"container_code\":\"2222222222\"}]"
  46. }
  47. }
  48. }
  49. }
  50. ```
  51. 问到某家店时传 `shop`(店铺名或环境 ID);不传用默认店。不设 `ETSY_SHOPS` 时,自动用密钥文件里已授权的店。
  52. | 环境变量 | 说明 |
  53. |---|---|
  54. | `ETSY_SHOPS` | 店铺数组:`name`、`container_code`(HubStudio 环境 ID)、`default` |
  55. | `ETSY_CONTAINER_CODE` | 只有一家店时可以只写环境 ID |
  56. | `ETSY_API_KEYS` | 应用密钥和店铺授权文件,默认 `~/.config/etsy-seller-mcp/api-keys.json`(600 权限,换电脑时原样拷过去) |
  57. | `ETSY_DATA_DIR` | 预检记录、执行日志(`write-log.jsonl`)、锁,默认 `~/.etsy-seller-mcp` |
  58. | `ETSY_READ_ONLY` | `true` = 只读,不允许任何写操作 |
  59. | `HUBSTUDIO_API` | HubStudio 本地接口,默认 `http://127.0.0.1:6873`(只有 auth 用) |
  60. ## 注意
  61. - **额度**:每个应用 10 次 / 秒、1 万次 / 天(Etsy 后台可看)。本工具每进程限 5 次 / 秒;遇到限流会说明,不会反复重试。
  62. - **分页**:每页最多 100 条,`offset` 最大 12000。
  63. - **费用**:草稿发布 / 商品从下架、过期改成在售时 Etsy 收 0.20 美元刊登费,预检会提示。
  64. - **库存 / 价格 / 规格(updateListingInventory)是整组替换**;Etsy 现在要求每个 offering 带 `readiness_state_id`(处理时间配置,`getShopReadinessStateDefinitions` 查)。
  65. - **结果不确定时**:修改 / 删除类用同一个 `preview_id` 再执行会先对账、可安全重发;创建 / 上传 / 加运单类不会自动重发,要先查询确认。
  66. - **账本金额**按最小货币单位记,`etsy_finance` 已除以 100。
  67. - 调 Etsy 接口走本机网络(Node 不读系统代理);HubStudio 只在授权时用。
  68. - 接口目录来自官方 OpenAPI(`spec/etsy-oas-3.0.0.json`),更新:下载新版覆盖后 `npm run build-spec`。
  69. ## 开发
  70. ```bash
  71. npm test
  72. node bin/etsy-seller-mcp.mjs --help
  73. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.