Skip to main content
Glama

etsy-mcp

第一个用于 Etsy 的生产级模型上下文协议 (MCP) 服务器。在五分钟内将 Claude 连接到您的 Etsy 店铺商品、库存、订单和统计信息 —— 仅限读取。

License: MIT Python 3.10+ MCP

为什么会有这个项目

Etsy 的 Open API v3 文档齐全且稳定,但每个想要在店铺之上使用 LLM 的卖家最终都要从零开始编写相同的 OAuth 和分页逻辑。现有的 MCP 集成大多是简单的演示,缺少令牌刷新、重试逻辑以及 Etsy 实际要求的按店铺分页功能。

如果您在 Etsy 上销售,并且希望 Claude(或任何支持 MCP 的 AI 助手)能够直接了解您店铺的情况 —— 比如有哪些商品、昨天发了什么货、哪些库存不足 —— 那么这个差距就是“开箱即用地总结今日订单”与“需要自定义集成才能总结今日订单”之间的区别。

etsy-mcp 填补了这一空白。它是一个轻量级、经过充分测试且采用 MIT 许可的 MCP 服务器,向任何 MCP 客户端公开了八个只读的 Etsy 端点。它基于多年大规模运行电子商务自动化的经验构建。

Related MCP server: @mcpengine/etsy

您可以用它做什么

将此服务器连接到 Claude Code、Claude Desktop 或任何 MCP 主机,然后询问如下问题:

  • “在我的店铺中搜索标题中带有 vintage 字样的商品,并告诉我哪些库存少于 5 件。”

  • “我昨天收到了多少订单?按买家和总收入分组。”

  • “拉取收据 5550001,告诉我哪些交易已发货,还有哪些尚未发货。”

  • “过去 30 天我的店铺统计数据如何?比较订单、收藏者和在售商品数量。”

  • “对于商品 1234567890,向我展示每一个变体、其 SKU 和当前数量。”

Claude 直接读取您的店铺。无需复制粘贴,无需电子表格,无需自定义流水线。

工具 (v0.1,均为只读)

工具

功能

etsy_search_listings

在在售商品中进行关键词搜索,可选择店铺范围。

etsy_get_listing

通过 ID 获取单个商品。

etsy_get_shop

获取店铺记录(名称、货币、计数、休假状态等)。

etsy_search_orders

列出指定日期窗口内一个店铺的收据(订单)。

etsy_get_order

通过 ID 获取单个收据,包括行项目交易。

etsy_get_inventory

获取商品的变体级库存(SKU、数量、价格)。

etsy_get_shop_stats

组合周期汇总:订单、收藏者、收入、商品。

etsy_get_active_listings

店铺中所有在售商品的分页列表。

写入端点(创建草稿商品、更新库存、标记收据已发货)在 v0.1 中特意未包含。一旦只读功能稳定,计划在 v0.2 中加入。

安装

pip install etsy-mcp

v0.1 从此仓库发布。PyPI 发布正在进行中 —— 目前,请使用 pip install git+https://github.com/alveyautomation/etsy-mcp 安装,或克隆并在本地运行 pip install -e .。

配置凭据

服务器从环境变量中读取所有内容。将 .env.example 复制到 .env 并填写您的租户信息:

ETSY_API_URL=https://api.etsy.com/v3/application/   # default; usually leave alone
ETSY_API_KEY=your-keystring-from-etsy-developers
ETSY_REFRESH_TOKEN=oauth2-refresh-token-for-your-shop
ETSY_DEFAULT_SHOP_ID=                               # optional fallback
ETSY_HTTP_TIMEOUT=60                                # optional, seconds
ETSY_MAX_RETRIES=3                                  # optional

获取 Etsy API 密钥

  1. 访问 https://www.etsy.com/developers/your-apps 并注册一个应用。

  2. 复制 Keystring —— 这就是 ETSY_API_KEY。

  3. 为您的一次性 OAuth 引导配置重定向 URI(例如 http://localhost:3000/callback)。

获取刷新令牌

Etsy 使用 带有 PKCE 的 OAuth 2.0。要进行引导,请使用以下参数运行一次标准的 OAuth-PKCE 流程:

  • response_type=code

  • client_id=<您的 keystring>

  • redirect_uri=<您注册的 URI>

  • scope=listings_r shops_r transactions_r(只读 —— 这是此服务器所需的最低权限)

  • state=<随机字符串>

  • code_challenge=<PKCE> 和 code_challenge_method=S256

将生成的授权码在 POST https://api.etsy.com/v3/public/oauth/token 处交换以获取访问令牌 + 刷新令牌。将 刷新令牌 保存为 ETSY_REFRESH_TOKEN。服务器将自动使用它来生成短期的访问令牌。

使用最小权限的只读令牌。 v0.1 仅调用 GET 端点,但纵深防御意味着您永远不应授予服务器刷新令牌写入权限 (*_w)。当 v0.2 推出写入工具时,通过生成一个新的更高权限令牌来选择加入 —— 永远不要反过来操作。

连接到 Claude Code

添加到 ~/.claude/claude_code_config.json(或您项目的 MCP 配置):

{
  "mcpServers": {
    "etsy": {
      "command": "etsy-mcp",
      "env": {
        "ETSY_API_KEY": "your-keystring",
        "ETSY_REFRESH_TOKEN": "your-refresh-token",
        "ETSY_DEFAULT_SHOP_ID": "12345678"
      }
    }
  }
}

重启 Claude Code。八个 etsy_* 工具将出现在任何新会话中。

连接到 Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows),并添加与上述相同的 mcpServers 块。重启桌面应用。

工具参考

每个工具都返回一个 JSON 信封:

{ "ok": true,  "data": { ... } }
{ "ok": false, "error": "human-readable message" }

etsy_search_listings

etsy_search_listings(
    query: str,                          # required
    shop_id: int | None = None,          # scope to a single shop
    limit: int = 50,                     # max 100 (Etsy server cap)
)

当提供 shop_id 时,它会访问 /shops/{shop_id}/listings/active。否则,它会访问全局 /listings/active 索引。

etsy_get_listing

etsy_get_listing(listing_id: int)

返回商品记录,如果 404 则返回 data: null。

etsy_get_shop

etsy_get_shop(shop_id: int)

店铺记录包括 shop_name、currency_code、listing_active_count、num_favorers、is_vacation 等。

etsy_search_orders

etsy_search_orders(
    date_from: str,                      # ISO date "YYYY-MM-DD"
    date_to: str,                        # ISO date "YYYY-MM-DD"
    shop_id: int | None = None,          # falls back to default
    status: str | None = None,           # 'open' | 'unshipped' | 'completed' | 'all'
    limit: int = 200,                    # max 1000
)

Etsy 将页面大小限制为 100;分页是透明的。当 limit 是截断点时,响应包含 limit_reached: true。

etsy_get_order

etsy_get_order(receipt_id: int, shop_id: int | None = None)

返回完整收据(包含 transactions[]),如果 404 则返回 data: null。

etsy_get_inventory

etsy_get_inventory(listing_id: int)

返回包含 sku、property_values 和 offerings[](数量、价格、启用状态)的 products[]。使用 offering 数量作为每个变体的规范“可售数量”。

etsy_get_shop_stats

etsy_get_shop_stats(shop_id: int, period: str = "30d")

一个组合汇总。Etsy 在 v3 中没有公开一流的 shop/stats 端点,因此这是从店铺记录(收藏者、在售商品数量)和窗口内的收据中合成的。返回形状:

{
  "shop_id": 12345678,
  "period": "30d",
  "period_days": 30,
  "date_from": "2026-03-27",
  "date_to": "2026-04-26",
  "favorers": 314,
  "active_listings": 87,
  "orders": 42,
  "revenue_minor_units": 152400,
  "currency_code": "USD"
}

period 接受 <N>d 格式,最多 365 天。

etsy_get_active_listings

etsy_get_active_listings(shop_id: int, limit: int = 200)

店铺中所有在售商品的分页转储。对于全目录推理(“审计我的标题中缺失的关键词”)很有用。软上限为 1000,以保持单次工具调用的边界。

本地开发

git clone https://github.com/alveyautomation/etsy-mcp
cd etsy-mcp
python -m venv .venv && source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest                                                # 49 tests, ~3s

预提交钩子(gitleaks, trufflehog, ruff, formatter, 租户指纹清理器):

pip install pre-commit
pre-commit install

针对真实 Etsy 沙盒的集成测试受 ETSY_INTEGRATION_TESTS=1 控制。正常贡献不需要它们。

故障排除

Failed to refresh Etsy access token —— 您的刷新令牌已过期或被撤销。Etsy 刷新令牌自签发之日起 90 天内有效,但前提是必须定期使用。重新运行 OAuth-PKCE 引导以生成新的令牌。

Missing required environment variables —— 服务器在加载 .env 之前尝试启动。请在父 shell 中导出变量,或确保您的 MCP 主机配置在 env 块中包含了它们。

HTTP 403 on receipts/transactions —— 刷新令牌的范围缺少 transactions_r。使用上述列出的只读范围重新引导。

Empty results despite known data —— 确认 shop_id。Etsy 的 /shops/{shop_id}/... 端点仅返回 OAuth 令牌已授权的店铺的数据。

Pagination feels slow —— Etsy 将每个请求的页面大小限制为 100,而不是我们。对于较大的日期窗口(长订单历史记录),预计会有多次往返。降低 limit 参数以限制调用。

贡献

欢迎提交问题和拉取请求。请:

  • 在打开 PR 之前运行 pytest (pip install -e ".[dev]")。

  • 运行 pre-commit run --all-files。

  • 将 v0.1 的新增内容保持在只读范围内。写入端点将在 v0.2 中加入。

  • 测试中仅使用合成数据 —— 不要使用真实的店铺名称、商品 ID 或收据编号。

许可证

MIT —— 参见 LICENSE。

免责声明

etsy-mcp 是一个非官方的第三方集成。它未得到 Etsy, Inc. 的认可、关联或支持。“Etsy”是 Etsy, Inc. 的商标。使用风险自负;在依赖它进行生产决策之前,请先针对您的店铺验证其行为。

Available Tools

8 tools
etsy_get_active_listingsA

List active listings for a shop, paginating transparently.

Args: shop_id: Etsy ShopID. limit: Soft cap on yielded listings (default 200, max 1000).

Returns: JSON envelope. data.listings is the list of active-listing records.

Inputs: shop_id (required), limit. Returns: result

etsy_get_inventoryA

Fetch the current inventory record (variations + offerings) for a listing.

Args: listing_id: Etsy ListingID.

Returns: JSON envelope. data is the inventory record (with products[] carrying property values, SKU, price, and offerings[] with quantity), or null if absent.

Inputs: listing_id (required). Returns: result

etsy_get_listingA

Fetch the full record for a single listing.

Args: listing_id: Etsy ListingID (integer).

Returns: JSON envelope. data is the listing record, or null if not found.

Inputs: listing_id (required). Returns: result

etsy_get_orderB

Fetch full receipt (order) detail including transactions.

Args: receipt_id: Etsy ReceiptID (integer). shop_id: Etsy ShopID. Falls back to ETSY_DEFAULT_SHOP_ID if omitted.

Returns: JSON envelope. data is the receipt record, or null if missing.

Inputs: receipt_id (required), shop_id. Returns: result

etsy_get_shopA

Fetch the shop record for a single shop.

Args: shop_id: Etsy ShopID (integer).

Returns: JSON envelope. data is the shop record (with name, currency_code, listing_active_count, num_favorers, etc.), or null if not found.

Inputs: shop_id (required). Returns: result

etsy_get_shop_statsA

Return aggregated stats (orders, favorers, active listings, revenue) for a shop over the given period.

Args: shop_id: Etsy ShopID. period: Lookback window in the form 'd', e.g. '7d', '30d', '90d'. Maximum 365 days.

Returns: JSON envelope. data is a dict with orders, favorers, active_listings, revenue_minor_units, currency_code, and the resolved date_from / date_to.

Inputs: shop_id (required), period. Returns: result

etsy_search_listingsA

Search active Etsy listings by keyword.

Args: query: Free-text keyword search across listing title and tags. shop_id: Optional Etsy ShopID to scope the search to a single shop. When omitted, queries the global active-listings index. limit: Cap on returned results (max 100 enforced by Etsy).

Returns: JSON envelope: {"ok": true, "data": {"results": [...], "count": N}}.

Inputs: query (required), shop_id, limit. Returns: result

etsy_search_ordersA

Search receipts (orders) created in the inclusive [date_from, date_to] window for a shop.

Args: date_from: ISO date (YYYY-MM-DD), start of window. date_to: ISO date (YYYY-MM-DD), end of window. shop_id: Etsy ShopID to scope the search to. Falls back to ETSY_DEFAULT_SHOP_ID if omitted. status: Optional receipt status filter ('open', 'unshipped', 'unpaid', 'completed', 'processing', 'all'). limit: Cap on yielded receipts (default 200, max 1000). Etsy caps page size at 100 per request; pagination is handled transparently.

Returns: JSON envelope. data.orders is the list of receipt records.

Inputs: date_from (required), date_to (required), shop_id, status, +1 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct resource (listings, inventory, shop, orders) and operation (get, search, stats), with no overlapping purposes.

    Naming Consistency5/5

    All tools follow the consistent pattern 'etsy_<verb>_<noun>', using snake_case and clear verbs (get, search) throughout.

    Tool Count4/5

    8 tools is reasonable for an Etsy API wrapper, covering key read operations without being excessive.

    Completeness2/5

    The server provides only read/search operations; missing critical mutation tools like create/update/delete listing or update order, leaving significant gaps for full lifecycle management.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A full-featured MCP server for the Etsy Open API v3 that enables managing an Etsy shop, including listings, inventory, images, digital files, and orders, through Claude or any MCP-compatible client.
      26
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A custom MCP server exposing database, ticketing, and external-API tools to both Claude Desktop and a self-built autonomous agent powered by Groq's free-tier LLaMA 3.3.
      -