SellerSprite MCP

简体中文 | English

让 AI Agent 直接读取和调用卖家精灵数据。

解决的问题

卖家精灵的大部分数据依赖网页登录状态或浏览器扩展状态。普通 Agent 即使知道要查询什么，也会遇到几个问题：

• Agent 只能看到网页，不能稳定读取页面背后的结构化数据；
• 网页接口需要 Cookie，扩展接口还需要动态签名和扩展登录状态；
• 不同功能使用不同的 URL、请求方法、字段名称、分页和枚举；
• Agent 不知道某个选品问题应该调用哪个功能，也不知道参数如何填写；
• 直接把网页内容交给 Agent，会消耗大量上下文并产生不稳定的解析结果。

SellerSprite MCP 把这些问题统一封装起来。Agent 只需要选择操作并提供业务参数，MCP 会完成：

1. 将 Agent 参数转换为卖家精灵当前网页请求；
2. 注入本机网页登录状态或扩展登录状态；
3. 生成扩展接口所需的动态参数并处理可续期授权；
4. 调用真实的 www.sellersprite.com 接口；
5. 返回结构化 JSON 数据。

项目目前覆盖 40 个已经映射和验证的卖家精灵功能，包括选产品、查竞品、ASIN、关键词、流量、ABA、选市场和评论数据。

MCP 工具

服务只暴露五个稳定工具，避免让 Agent 面对 40 个独立工具：

工具	用途
sellersprite_session_status	检查 CDP、网页和扩展登录状态，不返回 Cookie、Token 等认证内容
sellersprite_login	使用默认 Chromium 浏览器打开登录页，等待用户完成登录并读取登录态
sellersprite_list_operations	按名称、用途、认证类型或网页端点查找功能
sellersprite_describe_operation	查看功能说明、输入参数、网页请求、默认值、枚举和前置条件
sellersprite_call	执行指定功能并返回结构化结果

Agent 的标准调用顺序是：

session_status -> [login] -> list_operations -> describe_operation -> call

已覆盖功能

• 产品：选产品、查竞品、产品类目、ASIN 详情、销量与优惠趋势、Keepa 趋势、BSR 销量预测。
• 关键词：关键词反查、关键词选品、关键词挖掘、拓展流量词、出单词反查、谷歌趋势。
• 流量：关联流量、流量词统计、流量来源、关键词流向。
• ABA：按周选品、按月选品、关键词趋势。
• 市场：市场列表、统计、商品/品牌/卖家集中度及各类分布趋势。
• 评论：星级、图片、视频、VP、Vine 评论筛选与明细。

完整操作目录位于 data/operations.json。每项操作都包含中文功能说明、Agent 输入、实际网页请求模板、字段含义、响应说明和验证证据。

环境要求

• Node.js 22 或更高版本，并确保 node 位于 PATH；
• 已登录的卖家精灵网页账号；
• 调用扩展功能时，需要安装并登录卖家精灵 Chrome 扩展。

项目没有运行时 npm 依赖，下载后可以直接启动。

MCP 安装

推荐直接从 GitHub 安装为全局 npm 命令，无需克隆仓库，也不依赖固定目录：

node --version
npm --version
npm install -g github:JieXi-11/SellerSprite
npm list -g sellersprite-mcp --depth=0

node --version 需要输出 v22 或更高版本。安装命令执行后，sellersprite-mcp 必须位于当前终端的 PATH；重新启动 Codex 后再添加 MCP。

安装后系统中会提供 sellersprite-mcp 命令。MCP 客户端使用以下配置即可启动服务：

{
  "mcpServers": {
    "sellersprite": {
      "command": "sellersprite-mcp",
      "args": [],
      "env": {
        "SELLERSPRITE_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

完整示例位于 mcp.example.json。

快速开始

1. 获取项目

git clone https://github.com/JieXi-11/SellerSprite.git
cd SellerSprite
node --check src/server.mjs
node --test "test/*.test.mjs"

2. 登录浏览器

安装 MCP 后可以让 Agent 调用 sellersprite_login。工具会在 Windows、macOS 和 Linux 上寻找 Chrome、Edge、Brave 或 Chromium，并使用当前系统对应的持久化配置目录。

也可以手动启动专用调试浏览器。

Windows：

关闭使用同一用户目录的 Chrome 后，通过远程调试端口启动：

$chrome = "$env:ProgramFiles\Google\Chrome\Application\chrome.exe"
$profile = "$env:LOCALAPPDATA\SellerSpriteMCP\Chrome"
& $chrome --remote-debugging-port=9222 --user-data-dir=$profile

macOS：

"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/Library/Application Support/SellerSpriteMCP/Chrome"

Linux：

google-chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="${XDG_CONFIG_HOME:-$HOME/.config}/sellersprite-mcp/chrome"

首次启动后，在这个 Chrome 中完成：

1. 登录 https://www.sellersprite.com；
2. 安装卖家精灵 Chrome 扩展；
3. 在扩展中登录；
4. 保持 Chrome 运行。

MCP 会通过 CDP 实时读取卖家精灵 Cookie、浏览器 User-Agent 和扩展 chrome.storage.local。认证状态更新后会自动用于下一次调用，不需要维护 session.json 或扩展 Token 文件。

也可以让 Agent 调用：

调用 sellersprite_login，打开登录窗口并等待 180 秒。

sellersprite_login 会在当前操作系统中寻找 Chrome、Edge、Brave 或 Chromium，并使用持久化的 MCP 专用用户目录打开卖家精灵登录页。用户直接在浏览器中输入账号密码，凭据不会经过 Agent 或 MCP；登录完成后，MCP 自动读取登录态。首次登录后，后续会复用该专用用户目录。

检查 CDP 是否启动：

Invoke-RestMethod http://127.0.0.1:9222/json/version

3. 启动 MCP

在项目根目录运行：

node scripts/start-mcp.mjs

使用其他调试端口时：

$env:SELLERSPRITE_CDP_URL = "http://127.0.0.1:9333"
node src/server.mjs

接入 Codex

先安装全局命令，再注册到 Codex：

npm install -g github:JieXi-11/SellerSprite
codex mcp add sellersprite --env SELLERSPRITE_CDP_URL=http://127.0.0.1:9222 -- sellersprite-mcp

检查注册结果：

codex mcp get sellersprite

在“连接至自定义 MCP”界面填写

先执行上面的 npm install -g，然后按以下内容填写：

界面字段	填写内容
名称	sellersprite
类型	STDIO
启动命令	sellersprite-mcp
参数	留空
环境变量键	SELLERSPRITE_CDP_URL
环境变量值	http://127.0.0.1:9222
环境变量传递	留空

Windows 客户端提示找不到启动命令时，将启动命令填写为 sellersprite-mcp.cmd。保存配置后重新加载 MCP，并调用 sellersprite_session_status 检查连接。

如果 Codex 显示 Skill 已加载但 MCP 工具列表为空，说明旧插件仍在运行或 MCP 进程启动失败。停用旧的 SellerSprite 插件，确认 node、npm 和 sellersprite-mcp 在启动 Codex 的用户环境中可执行，然后创建新任务。MCP 工具显示在工具列表中，不显示为 @ 插件标签。

更新项目时重新执行 npm install -g github:JieXi-11/SellerSprite。MCP 使用全局命令启动，因此仓库克隆位置、盘符和用户目录不会进入 Codex 配置。

登录工具如何使用

完成 MCP 配置并重新加载 Codex 后，可以直接对 Agent 说：

使用 SellerSprite MCP 检查登录状态。如果没有登录，打开卖家精灵登录窗口并等待我完成登录。

Agent 会先调用：

{}

对应工具为 sellersprite_session_status。如果返回 ready: false，Agent 接着调用：

{
  "waitSeconds": 180
}

对应工具为 sellersprite_login。该调用会：

1. 在当前操作系统中寻找受支持的 Chromium 浏览器；
2. 确认浏览器是 Chrome、Edge、Brave 或 Chromium；
3. 使用当前操作系统对应的持久化用户目录；
4. 启动 9222 CDP 调试端口；
5. 打开卖家精灵登录页；
6. 等待用户在浏览器中完成登录；
7. 登录成功后返回浏览器类型、Cookie 数量和当前页面，不返回 Cookie 内容。

账号和密码只在卖家精灵网页中输入，不要放入 Agent 提示词或 MCP 参数。

waitSeconds 的取值范围是 0 到 300：

值	行为
180	推荐；打开窗口并等待最多三分钟
0	只打开登录窗口并立即返回，登录后再调用 sellersprite_session_status
300	登录过程包含验证码或第三方登录时使用

首次网页登录成功后，该登录态保存在专用浏览器目录中。以后通常只需要调用 sellersprite_session_status；Cookie 失效时再调用 sellersprite_login。

扩展认证与网页登录是两套状态。调用 BSR 销量预测等扩展功能前，还需要在同一个专用浏览器中安装卖家精灵扩展并登录一次。sellersprite_session_status 返回 extension.valid: true 时，扩展功能才已就绪。

如果调用登录工具后没有出现窗口，检查：

Invoke-RestMethod http://127.0.0.1:9222/json/version

也可以通过 SELLERSPRITE_BROWSER_PATH 和 SELLERSPRITE_BROWSER_PROFILE 覆盖自动发现结果。

接入其他 MCP 客户端

使用支持 stdio MCP 的客户端时，配置结构通常如下：

{
  "mcpServers": {
    "sellersprite": {
      "command": "sellersprite-mcp",
      "args": [],
      "env": {
        "SELLERSPRITE_CDP_URL": "http://127.0.0.1:9222"
      }
    }
  }
}

Agent 如何使用

Agent 安装 MCP 后不需要自行猜测网页接口。推荐提示词：

先检查 SellerSprite 登录状态，再查找与“评论”有关的操作。
读取操作说明后，查询 ASIN B09BF6XJY1 的五星评论，每页返回 5 条。

Agent 会依次调用：

1. sellersprite_session_status
2. 登录态失效时调用 sellersprite_login({"waitSeconds":180})
3. sellersprite_list_operations({"query":"评论"})
4. sellersprite_describe_operation({"operation":"review"})
5. sellersprite_call(...)

最终调用参数示例：

{
  "operation": "review",
  "params": {
    "marketplace": "US",
    "asin": "B09BF6XJY1",
    "starList": [5],
    "typeList": [],
    "page": 1,
    "size": 5
  }
}

选市场示例提示词：

使用 SellerSprite 查找选市场相关功能，读取参数说明后，
查询美国站指定类目最近 30 天的商品集中度、品牌集中度和价格分布。

操作说明结构

调用 sellersprite_describe_operation 后会返回：

字段	含义
title / description	功能名称和使用目的
authentication	使用网页 Cookie、扩展状态或混合认证
tool_input	Agent 调用 sellersprite_call 时应传入的参数
web_request	MCP 实际发送的网页端点、方法、模板和字段
defaults / enums	默认值和枚举
precondition	评论语料等数据前置条件
web_response	响应字段和语义
verification	真实请求验证记录

环境变量

环境变量	用途	默认值
SELLERSPRITE_CDP_URL	已登录 Chrome 的调试地址	http://127.0.0.1:9222
SELLERSPRITE_BROWSER_PATH	可选；覆盖自动识别的 Chromium 浏览器程序	自动发现
SELLERSPRITE_BROWSER_PROFILE	可选；覆盖当前系统的登录浏览器持久化目录	按操作系统自动选择
SELLERSPRITE_CALL_TIMEOUT_MS	单次调用超时毫秒数	120000
SELLERSPRITE_MAX_OUTPUT_BYTES	单次响应最大字节数	20971520

自动配置目录：

系统	默认目录
Windows	%LOCALAPPDATA%\SellerSpriteMCP\Chrome
macOS	$HOME/Library/Application Support/SellerSpriteMCP/Chrome
Linux	${XDG_CONFIG_HOME:-$HOME/.config}/sellersprite-mcp/chrome

测试

协议和操作目录测试：

node --test test/protocol.test.mjs

网页真实请求测试：

$env:SELLERSPRITE_LIVE_TEST = "1"
node --test test/live.test.mjs

扩展真实请求测试：

$env:SELLERSPRITE_LIVE_EXTENSION_TEST = "1"
node --test test/live.test.mjs

常见问题

网页请求返回登录错误

在 CDP 附加的 Chrome 中重新登录卖家精灵，然后再次调用 sellersprite_session_status。下一次请求会自动读取最新 Cookie。

扩展请求返回重新认证状态

在 CDP 附加的 Chrome 中打开卖家精灵扩展并重新登录。下一次扩展调用会直接读取最新的 chrome.storage.local。可续期状态由适配器自动处理。

评论接口返回空列表

网页登录态评论接口依赖账号中已有的评论分析语料。先在卖家精灵评论分析页面采集对应 ASIN，再调用评论接口。

Agent 不知道调用哪个操作

让 Agent 先调用 sellersprite_list_operations 搜索业务关键词，再调用 sellersprite_describe_operation。不要直接猜测操作名称和参数。

数据与认证安全

• 默认 CDP 模式不把 Cookie、扩展 Token 或 UUID 写入项目文件；
• 调试端口应只监听本机，不要向局域网或公网开放；
• 备用文件模式中的 session.json、extension-state.json、.env 和日志文件均被忽略；
• sellersprite_session_status 只报告状态，不返回认证值。