# Etsy 数据查询 · AI 使用指南（MCP 连接版）

## MCP 是什么？

简单说，MCP 就像给 AI 装了一个"实时数据插件"。平时你问 AI 问题，它只能凭
训练时学到的旧知识回答，不知道 Etsy 上现在的商品、价格、评价是什么样。装上
这个插件之后，AI 每次遇到跟 Etsy 数据相关的问题，会**临时查一次实时数据、
查完就用来回答你**，不会把数据留在 AI 那边，也不会把你的账号信息交给 AI 或
第三方——每次查询都是拿你自己的密钥现场验证身份，用完即走，跟你自己打开
浏览器去查一次是一样的效果，只是不用你自己动手。

你可以直接用平时聊天的方式问 AI 问题，比如"帮我搜一下 xxx 关键词最近排名
靠前的商品"，AI 会自己去查数据、整理好给你看。

---

## 一、你需要准备什么

| 项目     | 内容                                                                                   |
| -------- | -------------------------------------------------------------------------------------- |
| 连接地址 | `https://app.sellerbutler.com/mcp`                                                     |
| 认证方式 | HTTP Header：`X-Api-Key: 你的密钥`                                                     |
| 传输协议 | Streamable HTTP                                                                        |
| 你的密钥 | 联系 Nick 获取（微信：`CuriousNick`） |

> ⚠️ 密钥等同于账号密码，请勿分享给他人或粘贴到公开的群聊、论坛。
> 如果怀疑密钥泄露，请联系 Nick（微信：`CuriousNick`）重置。

---

## 二、按你使用的 AI 工具配置

### 方式 A：Claude Desktop / Claude Code（推荐，已验证可用）

打开 MCP 配置文件（Claude Desktop 在设置里的 "Developer" → "Edit Config"；
Claude Code 用 `claude mcp add` 命令或直接编辑配置文件），加入以下内容：

```json
{
  "mcpServers": {
    "etsy-listing-tools": {
      "type": "http",
      "url": "https://app.sellerbutler.com/mcp",
      "headers": {
        "X-Api-Key": "你的密钥"
      }
    }
  }
}
```

保存后重启 Claude，正常情况下会在工具列表里看到 5 个新工具，说明连接成功。

### 方式 B：腾讯元宝（通过「元器」创建智能体接入）

腾讯元宝目前不支持在普通对话框里直接添加自定义 MCP，需要先在它的智能体
平台「腾讯元器」（元宝 Agent 的另一个名字）里创建一个智能体，再把 MCP
接进这个智能体：

1. 登录 [https://yuanqi.tencent.com/my-creation/agent](https://yuanqi.tencent.com/my-creation/agent)
2. 点击「创建智能体」→ 选择「对话式智能体」，填写名称和简介（比如
   "Etsy 数据助手"）
3. 进入智能体的插件配置页，选择「自定义 MCP 插件」
4. 填写 MCP Server 信息：
   - 名称：随意，例如 `etsy-listing-tools`
   - URL：`https://app.sellerbutler.com/mcp`
   - Header 认证：Header 名填 `X-Api-Key`，值填你的密钥
5. 保存后回到智能体对话页，就可以用自然语言问它 Etsy 数据了

这一套比直接用 Claude 多几步，但配置一次之后可以长期使用。

### 方式 C：其他支持 Streamable HTTP 的 MCP 客户端

只要客户端支持 "Streamable HTTP" 传输方式，都可以用同样的三个信息完成连接：
地址、`X-Api-Key` Header、你的密钥。

### 暂不支持自定义 MCP 的工具

以下几款目前（2026 年 7 月）还没有开放让用户自行添加 MCP Server 的入口，
如果你常用这几款，暂时只能用附录里的「方法一」：

- **Kimi Work / Kimi 桌面版**（普通聊天助手版本，不是开发者用的 Kimi Code CLI）
- **豆包**

这块功能各家更新很快，如果你的工具现在不支持，过一阵子可以再问一下我们，
或者直接联系 Nick 确认最新情况。

---

## 三、连上之后，你可以直接这样问 AI

不需要记住工具名字，AI 会自动判断该用哪个工具。下面是可以直接复制粘贴的例子：

**选品 / 竞品研究**

> "帮我搜一下关键词 'wood keychain' 最近排名靠前的商品，价格区间在 5-15 美元之间的。"
> "查一下类目 xxx 下面卖得比较好的商品有哪些特点。"

**查看某个店铺**

> "帮我看看这个店铺（店铺 ID：12345678）都在卖什么商品。"

**批量查商品详情**

> "这几个商品 ID（1111111, 2222222, 3333333）的详情帮我拉一下，包括图片和物流信息。"

**口碑 / 评价分析**

> "这个商品最近的买家评价怎么样，有没有差评提到具体问题？"
> "帮我看看这个店铺整体的买家评价，总结一下常见的好评和差评点。"

AI 会自动调用对应的数据接口，把结果整理成人话讲给你听，你也可以继续追问
"再帮我按价格排个序"之类的后续问题。

---

## 四、常见问题

**Q：AI 说连不上 / 提示 401、403 怎么办？**
先检查密钥有没有填对、有没有多余的空格。如果密钥确认无误还是连不上，
可能是密钥已被禁用或过期，请到后台重置一个新的再试。

**Q：AI 返回"listing_ids 不能为空"或类似的报错？**
说明这次提问里 AI 没能提取出你想要的具体商品 ID 或关键词，换一种更明确的
说法重新问一次即可，比如把商品链接里的数字 ID 直接贴给它。

**Q：批量查询商品时结果里有 `failed_ids`？**
这是正常现象，说明这几个 ID 可能已下架、不存在或输入有误，不影响其他能查到
的商品正常返回，可以把这几个 ID 单独确认一下。

**Q：一次能查多少个商品 ID？**
单次批量查询最多 100 个，超过会被自动拦截并提示，请分批查询。

**Q：我的 AI 工具不支持 MCP 怎么办？**
可以用「方法一：接口文档直接粘贴」的方式（见附录），把接口说明和密钥一次性
交给支持代码执行的 AI（如 Kimi Work、Codex、Claude Code），同样可以完成查询，
只是每次新开对话都需要重新粘贴一次文档模板。

---

## 附录：方法一（不支持 MCP 时的备选方案）

如果你使用的 AI 工具暂不支持 MCP 连接，可以直接把下面这份模板连同你的密钥
一次性粘贴进对话框，AI 会照着文档里的接口说明自己发起请求：

*（此处保留原有的接口文档 + 密钥复制模板，内容不变，仅作为 MCP 方式不可用时
的备用选项。）*