内容
# 虾皮商品探索服务器
[](https://www.npmjs.com/package/@bintangtimurlangit/shopee-mcp)
[](./LICENSE)
[](https://github.com/bintangtimurlangit/shopee-mcp/actions)
[](https://github.com/bintangtimurlangit/shopee-mcp)
一个用于**探索虾皮**的 MCP 服务器 - 商品搜索和价格 - 适用于任何 MCP 客户端（Claude Desktop，Claude Code 等）。仅限发现：无卖家功能。
> **需要登录，只读。** 虾皮阻止匿名请求，因此这个**非官方**服务器通过您自己的登录浏览器会话读取公共数据（参见 [为什么使用浏览器？](#为什么使用浏览器)）。它不执行任何卖家或帐户操作。
**完整参考：** [文档](./docs/README.md) · **更新日志：** [CHANGELOG.md](./CHANGELOG.md) · **版本和发布：** [docs/RELEASES.md](./docs/RELEASES.md)
## 工具
| 工具 | 返回内容 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `search_products` | 关键词搜索，支持排序和分页 - 名称，价格，销量，评分，卖家位置，商品 ID，网址。 |
| `get_product_detail` | 单个商品 - 价格和折扣，品牌，条件，类别，评分，**评论数**，**销量**，库存，位置，描述。 |
### 工具注解
根据 [MCP 注解规范](https://modelcontextprotocol.io/) - 两个工具都是只读的，无副作用。
| 工具 | 只读 | 幂等 | 破坏性 |
| -------------------- | :-------: | :--------: | :---------: |
| `search_products` | ✓ | ✓ | – |
| `get_product_detail` | ✓ | ✓ | – |
## 为什么使用浏览器？
虾皮**不**提供开放的 API 或服务器渲染的商品 HTML。其 `/api/v4/*` 端点受到反欺诈门控（`error 90309999`）的保护，该门控需要 Shopee 自己混淆的 SDK 生成的每个请求的签名头（`af-ac-enc-dat`，`x-sap-sec`，...）。
所以这个服务器：
1. 驱动 **[CloakBrowser](https://github.com/CloakHQ/cloakbrowser)** - 带有二进制级指纹补丁的 Chromium - 针对您**登录一次**的**持久配置文件**。
2. **导航到真正的虾皮页面并拦截响应** 其自己的应用程序获取的响应，以便请求携带有效的签名。
浏览器必须运行 **有头**（虾皮检测无头）；在服务器上使用虚拟显示（`xvfb`）。
### 从 npm（推荐）
```bash
npm install -g @bintangtimurlangit/shopee-mcp # 下载 CloakBrowser 二进制文件（~200 MB，已缓存）
```
这会在您的 PATH 上放置两个命令：**`shopee-mcp`**（服务器）和 **`shopee-mcp-login`**（一次性登录）。或者，无需安装：`npx -y @bintangtimurlangit/shopee-mcp`。
### 从源码
```bash
git clone https://github.com/bintangtimurlangit/shopee-mcp.git
cd shopee-mcp
npm install # 还会下载 CloakBrowser 二进制文件（~200 MB，已缓存）
npm run build
```
### 1. 登录一次
虾皮阻止匿名请求，因此您需要登录一次。这会将会话保存到 `~/.shopee-mcp/chrome-profile`。
```bash
shopee-mcp-login # 全局安装 - 或，从源码克隆： npm run login
```
- 打开 CloakBrowser 窗口 - 登录，然后按 Enter。
- 在桌面 / WSLg 上，窗口正常显示。
- 仅在会话过期时重新运行。
### 2. 在您的 MCP 客户端上注册
服务器启动一个**有头**浏览器，因此它需要显示屏。在无头机器上，请使用 `xvfb-run` 包装。
Claude Desktop / Claude Code `mcpServers` 条目：
```json
{
"mcpServers": {
"shopee": {
"command": "xvfb-run",
"args": ["-a", "shopee-mcp"]
}
}
}
```
在具有真实显示的机器上，删除 `xvfb-run`：`"command": "shopee-mcp"`，`"args": []`。从源码克隆，使用 `"command": "node"`，`"args": ["/absolute/path/to/shopee-mcp/build/index.js"]`（在无头框上使用 `xvfb-run` 包装）。
## 配置
所有配置均为可选 - 参见 `.env.example`。复制到 `.env` 以覆盖。
| 变量 | 默认值 | 目的 |
| -------------------- | ------------------------------ | ------------------------------------ |
| `SHOPEE_DOMAIN` | `shopee.co.id` | 区域虾皮域名。 |
| `SHOPEE_PROFILE_DIR` | `~/.shopee-mcp/chrome-profile` | 保存登录会话的位置。 |
| `SHOPEE_HEADLESS` | `false` | 保持 `false` - 无头模式被检测。 |
| `CACHE_TTL_MS` | `30000` | 内存缓存寿命。 |
| `DEBUG` | `false` | 将启动/调试信息记录到 stderr。 |
## 开发
```bash
npm run lint # eslint
npm run format # prettier --write (format:check to verify)
npm run typecheck
npm test # live smoke test (needs a display; use xvfb-run on servers)
npm run dev # tsx watch
```
更多详情：**[docs/DEVELOPMENT.md](./docs/DEVELOPMENT.md)**。
## 故障排除
| 症状 | 可能原因 / 解决方法 |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `🔒 Not signed in` / 匿名请求错误 | 无/过期会话 → 运行 `npm run login`。 |
| `error 90309999` 或空结果 | 虾皮的反机器人门控拒绝了请求。确保您已登录并运行 **有头**（或通过 `xvfb-run`）；重试。 |
| 有效商品的读取返回为空 | 虾皮延迟加载；重试，并使用 `DEBUG=true` 检查。 |
| 更改后立即返回空或过时的结果 | 内存缓存 - 降低 `CACHE_TTL_MS` 或等待 TTL 过期。 |
| 无头的/服务器没有显示 | 使用 `xvfb-run -a …` 包装命令。 |
## 注意事项
- **需要登录。** 无会话 → 工具返回友好的“运行 `npm run login`”提示。
- **反机器人是不断变化的。** 免费的 CloakBrowser 二进制文件可能会随着虾皮更新检测而过时；CloakBrowser Pro 提供更新的补丁。
- 尊重虾皮的服务条款。本项目用于个人市场探索，不适用于大规模抓取。
## 贡献与安全
[CONTRIBUTING.md](./CONTRIBUTING.md) · [SECURITY.md](./SECURITY.md) · [Code of Conduct](./CODE_OF_CONDUCT.md)
## 许可证
[MIT](./LICENSE)
---
## 免责声明
本项目为**非官方**项目。它**不隶属于、授权、维护、赞助或认可**虾皮或 Sea Limited。
它通过驱动一个真实的登录浏览器会话来访问虾皮的网络应用程序，这可能会在没有通知的情况下更改 - 当虾皮更新其网站或反机器人行为时，某个工具可能会崩溃。它只读取公开可用的产品数据，不执行任何帐户操作。
您有责任使本软件的使用符合 [虾皮服务条款](https://shopee.co.id/docs/terms) 和适用法律。使用合理的请求量。所有产品名称、徽标和品牌均为其各自所有者的财产。
