Etsy

@pipeworx/etsy

通过 Etsy Open API v3 搜索在售商品——仅限三个只需 API key（无需 OAuth 用户令牌）的端点。

Pipeworx 的一部分（https://pipeworx.io）——一个 MCP 网关，将 AI Agent 连接到 1879+ 个实时数据源。这是一个独立的非官方集成，与上游提供方无关，未获其认可，也非由其发布。

工具

• etsy_search_listings(keywords?, limit?, offset?, sort_on?, sort_order?, min_price?, max_price?, taxonomy_id?, buyer_country?) — 全站在售商品搜索（findAllListingsActive）。
• etsy_search_shop_listings(shop_id, keywords?, limit?, offset?, sort_on?, sort_order?) — 在单个店铺中搜索在售商品（findAllActiveListingsByShop）。
• etsy_get_listing(listing_id) — 按 ID 获取一个商品（getListing）。

没有已售价格／可比商品数据——Etsy 的 v3 API 不提供此类数据。仅支持在售商品。

身份验证

仅支持自带密钥（BYO key）（_apiKey），需要 API key。访问 https://www.etsy.com/developers/register 注册免费应用，以获取 keystring 和共享密钥。传入 ?_apiKey=<keystring>；“Your Apps”页面显示的以冒号连接的 <keystring>:<shared_secret> 格式也受支持，且该包会为你处理差异（见下文注意事项）。

Etsy 的 v3 参考文档标明了每个端点所需的身份验证方式。只有上述三个端点仅需 api_key；其他所有端点（店铺／收据／用户管理、商品写入）都需要通过 Etsy 的人工商业审核流程签发的 OAuth 用户令牌——不在此包的范围内。如果 Etsy 审核之后授予更广泛的访问权限，应扩展此包，而不是另建一个包。

BYO 是已确定的方案，并非权宜之计：Bruce 于 2026-10-02（fleet #2632）裁定 stop-tracking——Pipeworx 不会注册或代理平台 Etsy 应用；网关清单中从未设置的 PLATFORM_ETSY_KEY 声明已移除，也不再有人尝试探测它。 注册 Etsy 应用需要使用密码登录 Etsy 账户，然后通过 Etsy 的人工“Personal Approval”审核。待审核应用返回的 403 与伪造密钥返回的 403 在字节层面完全相同，因此不存在能够结束等待的探测方式。不带密钥的调用会以“requires an API key”拒绝，并提供注册 URL。请注意：尚未使用获批密钥验证过此包的实时调用——首位使用真实获批 keystring 的调用者将进行实时验证。

数据源

• https://developers.etsy.com/documentation/reference/ — Etsy Open API v3。 基础 URL：https://openapi.etsy.com/v3/application。

给接手者的注意事项：

• Etsy 对 x-api-key 请求头的值说法前后矛盾，无法通过实验解决。 这三个端点的 api_key 参考文档记载的是纯 keystring；快速入门文档则展示了以冒号连接的 keystring:shared_secret 对（这实际上是 OAuth 令牌端点的 Basic 身份验证凭据）。等待 Etsy Personal Approval 的应用会返回 403，而伪造密钥也会返回字节层面完全相同的 403——已于 2026-09-09（fleet #1279）通过负向对照验证——因此在激活之前，无法通过探测判断两种请求头格式孰优。于是此包会先发送 keystring，且仅在收到 403 时，才使用调用者传入的原始值重试一次。在实时成功响应确认哪种格式有效之前，不要将其“简化”为单次调用。
• 此包几乎原样返回 Etsy 的响应 JSON（count + results，以及一个 source 字段），而不重新映射字段名称，因为 Listing 资源的确切结构只依据已发布的 OpenAPI 参考文档核对过，尚未通过已认证的实时响应检查（构建时没有可用的有效密钥——见上文“身份验证”）。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "etsy": {
      "url": "https://gateway.pipeworx.io/etsy/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/etsy/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall，以及整个网关范围内的其他工具。因此，你看到的工具数量会多于此表：目前，单个工具包端点除了列出该工具包自己的工具，还会列出大约 30 个共享工具。连接的 initialize 响应会说明确切的范围，是了解当天实际情况的权威依据。

这是有意为之，并非意外复用了多个服务。元工具可以让限定范围的连接回答此工具包无法处理的问题——通过 ask_pipeworx 在整个目录中路由——这样你就不必再添加第二个 MCP 服务。目前无法挂载不包含这些元工具的工具包端点；如果额外的架构所占用的上下文超过了路由带来的价值，那么请只连接一次完整网关，而不是连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出每个工具包的工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一个网关和相同的 1879+ 个数据源。唯一的区别是，哪个工具包的工具会被直接列出；无论连接哪一个，ask_pipeworx 都可以访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/etsy_search_listings \
  -H 'Content-Type: application/json' \
  -d '{"keywords":"vintage brass lamp","limit":10}'

首次调用无需账户。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/etsy_search_listings。查找工具包：使用 {"query":"..."} 调用 POST https://gateway.pipeworx.io/v1/tools/search_packs。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需经过网关：

{
  "mcpServers": {
    "etsy": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-etsy"]
    }
  }
}

或者直接运行以确认它能够启动：

npx -y @pipeworx/mcp-etsy

它通过 stdin/stdout 使用 MCP，并响应 initialize/tools/list/tools/call，但仅限此工具包的工具——不包含上述网关连接额外提供的任何共享元工具。相同的源代码，相同的工具，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以不用直接调用工具，而是用通俗英语提问——这既适用于上述工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Etsy data" })

网关会选择合适的工具并自动填写参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT