xianyu-mcp-server
by litongqian
README.md
# xianyu-mcp-server
[](https://www.python.org/)
[](https://github.com/DoLovya/xianyu-mcp-server/actions/workflows/ci.yml)
[](./LICENSE)
[](./pyproject.toml)
基于 `pyxianyu` 封装的闲鱼 MCP 项目，用于把闲鱼商品、会话、消息发送等能力接入支持 MCP 的客户端。
> **风险提示**：本项目仅供学习与技术研究使用。通过自动化手段操作闲鱼账号存在被平台风控、限制功能甚至封号的风险，使用者需自行承担一切后果。详见[免责声明](#免责声明)。
## 目录
- [鸣谢](#鸣谢)
- [项目概览](#项目概览)
- [项目结构](#项目结构)
- [功能特性](#功能特性)
- [已知限制](#已知限制)
- [环境要求](#环境要求)
- [快速开始](#快速开始)
- [客户端接入](#客户端接入)
- [推荐验证流程](#推荐验证流程)
- [常见问题](#常见问题)
- [相关文档](#相关文档)
- [使用协议](#使用协议)
- [免责声明](#免责声明)
- [贡献指南](./CONTRIBUTING.md)
## 鸣谢
- https://github.com/cv-cat/XianYuApis
- https://github.com/shaxiu/XianyuAutoAgent
- https://github.com/zhinianboke/xianyu-auto-reply
## 项目概览
仓库分两层：
- `pyxianyu`：闲鱼底层 HTTP / WebSocket 能力（推荐通过 PyPI 安装；仓库内 submodule 仅用于开发调试）
- `src/xianyu_mcp/`：面向 MCP 的工具封装
适合的使用场景：
- 在 Trae、Cherry Studio、Claude Desktop 等支持 MCP 的客户端中直接调用闲鱼能力
- 把闲鱼卖家工作流接入自定义 Agent / 工作流编排系统
- 作为后续自动客服、消息分发、店铺运维脚本的基础设施
## 项目结构
```text
xianyu-mcp-server/
├── src/
│ └── xianyu_mcp/
│ ├── __init__.py
│ ├── server.py # MCP 工具注册与入口
│ └── tools/
│ ├── __init__.py
│ └── xianyu_api_tools.py # 底层能力封装
├── third_party/
│ └── pyxianyu/ # 可选：pyxianyu 源码（git submodule，仅开发调试）
│ ├── src/pyxianyu/apis/ # auth_api, item_api, media_api
│ ├── src/pyxianyu/core/ # client, exceptions
│ ├── docs/ # 接口分析文档
│ ├── src/pyxianyu/message/ # 消息类型定义
│ ├── src/pyxianyu/utils/ # 签名、Cookie 处理
│ ├── src/pyxianyu/xianyu_live.py # WebSocket 消息收发
│ └── src/pyxianyu/xianyu_apis.py # HTTP API 封装
├── openspec/
│ └── changes/ # 规范驱动的变更记录
├── .trae/
│ ├── commands/ # OPSX 工作流命令
│ ├── skills/ # OpenSpec 技能定义
│ ├── specs/ # 规范归档
│ └── mcp.json # Trae MCP 配置
├── .env.example
├── .gitmodules
├── LICENSE
├── pyproject.toml
├── uv.lock
└── README.md
```
## 功能特性
当前 MCP 已开放这些工具：
| 工具名 | 说明 |
| ---------------------------- | ------------------------------------------------------------------- |
| `validate_login` | 校验当前 Cookie 是否有效，并尝试换取 `accessToken` |
| `refresh_login` | 刷新当前登录态 |
| `get_my_profile` | 获取当前登录用户个人信息（个人页导航数据） |
| `search_items` | 按关键词搜索闲鱼商品（支持分页与排序） |
| `get_item_detail` | 获取指定商品详情 |
| `get_item_edit_detail` | 获取指定商品在 PC 编辑页的编辑详情 |
| `list_my_items` | 拉取当前账号名下全部商品列表，并自动翻页聚合 |
| `downshelf_item` | 下架当前账号名下指定商品 |
| `reshelf_item` | 通过 PC 编辑重发布链路重新上架指定商品 |
| `edit_item` | 编辑指定商品信息（仅支持 PC 可编辑的实体商品） |
| `publish_physical_item` | 在闲鱼 PC 端发布全新实体商品，支持自动上传图片 |
| `upload_media` | 上传本地文件或 URL 素材，返回可复用的媒体 URL |
| `list_conversations` | 拉取最近会话列表 |
| `list_conversation_messages` | 拉取指定会话历史消息 |
| `send_text_message` | 主动发送文本消息 |
| `send_image_message` | 主动发送图片消息 |
| `qr_login_generate` | 生成扫码登录二维码（返回 session_id 与 base64 data-url） |
| `qr_login_status` | 查询扫码登录会话状态（含人脸验证二维码 data-url） |
| `qr_login_cookie` | 在扫码登录成功后获取完整 Cookie（已尽量补齐 `_m_h5_tk` 等关键字段） |
| `qr_login_save_env` | 显式将 `qr_login_cookie` 的结果写入 `.env`（无需手动复制） |
### 用户信息相关用法
- 获取当前账号的个人信息（昵称/头像/地区等以接口返回为准）：调用 `get_my_profile`，结果同时包含结构化 `profile` 与原始响应 `raw`（便于你自定义字段映射）。
### 多媒体相关用法
- 直接上传素材拿到可复用 URL：调用 `upload_media`，将返回的 `url` 保存起来，用于后续构造 `edit_item` payload 或消息内容。
- 发布商品图：优先直接用 `publish_physical_item(images=[...])`，内部会自动上传并构造 `imageInfoDOList`。
- 发送图片消息：调用 `send_image_message(image=...)`，支持本地绝对路径或 http/https URL。
## 已知限制
以下能力尚未做 MCP 化：
- 常驻监听消息
- 自动回复 Worker
- 语音/视频消息发送工具
底层 `third_party/pyxianyu` 的 `ItemApi` 已实现完整的商品发布原语链路：
- `prepublish_check`：发布前校验
- `preget`：获取发布/编辑所需预置参数
- `edit_item`：PC 编辑接口提交
- `build_reshelf_payload`：基于编辑详情构造重发布 payload
- `publish_item`：直接发布全新商品
MCP 层已从中封装出 `get_item_edit_detail`、`reshelf_item`、`edit_item`、`publish_physical_item` 等工具。`prepublish_check`、`preget` 等原语仍保留为底层调用能力，未单独暴露。
关于商品上下架，需要额外注意：
- `downshelf_item` 已验证可用于普通商品下架
- `reshelf_item` 本质上走的是 PC 端"编辑并重发布"链路
- 虚拟商品受闲鱼 PC 端发布管控，无法通过当前 MCP 重新上架（详见常见问题）
- 其余支持 PC 编辑的实物商品，当前已验证可以下架、也可以重新上架
如果后续要接 AI 自动客服，建议把"消息监听"和"MCP 短调用"拆成两个进程，不要把常驻循环直接塞进 MCP 主进程。
## 环境要求
- Python 3.11+
- `uv`（或使用 `pip` 替代，见常见问题）
- 闲鱼登录后的完整 Cookie（可手动抓取，或先启动 MCP 后使用 `qr_login_*` 工具扫码获取）
`uv` 安装方式：
**Windows（PowerShell，推荐）**：
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
安装完成后**关闭并重新打开终端**（或刷新 PATH），然后验证：
```powershell
uv --version
```
**macOS / Linux**：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
## 快速开始
### 安装并启用
#### MCP 客户端配置（uvx 写法）
```json
{
"mcpServers": {
"xianyu-mcp-server": {
"command": "uvx",
"args": ["--from", "xianyu-mcp-server", "xianyu-mcp-server"],
"env": {
"XIANYU_COOKIE": "",
"XIANYU_COOKIE_FILE": ""
}
}
}
}
```
#### Cookie 配置
二选一即可：
- **方式一：直接写入完整 Cookie**：在 `env` 中填写 `XIANYU_COOKIE`
- **方式二：Cookie 存放在单独文件中**：在 `env` 中填写 `XIANYU_COOKIE_FILE` 指向文件路径（支持相对路径和绝对路径）
优先级：配置了 `XIANYU_COOKIE` 时，`XIANYU_COOKIE_FILE` 会被忽略。
#### 扫码登录（首次配置）
如果你暂时没有 Cookie：
- 先保持 `env` 为空启动 MCP
- 启动后服务会自动进入"首次配置模式"，在本机打开一个网页展示二维码（`127.0.0.1`），扫码成功后会自动把 Cookie 写回
- 调用 `qr_login_generate` 获取二维码并用手机闲鱼/淘宝扫码确认
- 持续调用 `qr_login_status` 直到 `status=success`（如遇风控可能进入 `verification_required`，按提示完成一次验证）
- 调用 `qr_login_cookie` 获取 Cookie
- 可选：调用 `qr_login_save_env` 将 Cookie 写入当前工作目录 `.env`（避免手动复制；写入后通常无需重启，下一次工具调用会自动读取新值）
首次配置模式相关开关（可选，通过 `env` 设置）：
```ini
XIANYU_SETUP_ENABLED=1 # 0 表示禁用首次配置模式
XIANYU_SETUP_AUTOSTART=1 # 0 表示启动时不自动弹出（但工具调用仍会返回 requires_login 引导）
XIANYU_SETUP_AUTO_OPEN=1 # 0 表示不自动打开浏览器/验证链接
XIANYU_SETUP_AUTO_WRITE_ENV=1 # 0 表示不自动写入 .env，需要你手动调用 qr_login_save_env
```
---
## 客户端接入
本项目基于标准 MCP 协议，支持任何兼容 MCP 的客户端。除 Cherry Studio 外均使用 `stdio` 传输模式。
统一使用以下 uvx 配置：
```json
{
"mcpServers": {
"xianyu-mcp-server": {
"command": "uvx",
"args": ["--from", "xianyu-mcp-server", "xianyu-mcp-server"],
"env": {
"XIANYU_COOKIE": "",
"XIANYU_COOKIE_FILE": ""
}
}
}
}
```
推荐优先使用 `XIANYU_COOKIE_FILE` 指向一个本地文件路径，避免把 Cookie 写进配置文件。
各客户端差异：
| 客户端 | 配置文件路径 | 支持 `${workspaceFolder}` | 备注 |
| -------------- | -------------------------------------------------------------------------- | ------------------------- | -------------------------------------------------------------------- |
| Trae | `.trae/mcp.json`（项目级）或 `~/.trae/mcp.json`（全局） | 项目级支持 | 配置后重载工作区；Trae 会基于 `env` 中出现的键渲染输入框 |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS） | 否 | 保存后重启 |
| Cursor | `.cursor/mcp.json`（项目级）或 `~/.cursor/mcp.json`（全局） | 项目级支持 | 全局配置需使用完整路径 |
| VS Code | `.vscode/mcp.json` | 是 | 使用 `"servers"` 字段（非 `"mcpServers"`），需显式 `"type": "stdio"`；需 VS Code 1.102+ |
| Cherry Studio | UI 配置，无配置文件 | N/A | 设置 → MCP 服务器 → 添加，类型选 STDIO，`command` 填 `uvx`，`args` 填 `--from xianyu-mcp-server xianyu-mcp-server` |
- `xianyu-mcp-server` 只是 MCP 服务名，可以自定义
- `command` 优先使用 `uvx`，可使用绝对路径，例如 `/Users/<user>/.trae/tools/uv/latest/bin/uvx`
- Windows 路径使用反斜杠，例如 `C:\Users\<user>\<path>\cookie.txt`
HTTP 模式（可选）：在 `args` 末尾追加 `"--http"` 启动后，监听 `http://localhost:8000/mcp`，Cherry Studio 等客户端可选 SSE 或 HTTP 类型接入。
## 推荐验证流程
接入完成后，建议按这个顺序验证：
1. 调用 `validate_login`，确认当前 Cookie 有效
2. 调用 `list_my_items`，确认能拉到自己的商品列表
3. 调用 `get_item_detail`，确认详情接口可用
4. 如需店铺运维动作，再调用 `downshelf_item`
5. 如需把已下架商品重新挂回去，再调用 `reshelf_item`
`list_my_items` 的 `page_size` 推荐使用默认值 `20`。某些账号或场景下，服务端会对单页条数做更严格限制，传过大可能返回 `FAIL_BIZ_FORBIDDEN`。
## 常见问题
### 1. `uvx` 启动报找不到命令
请先确认 uv 已安装并在 PATH 中可用：
```bash
uv --version
```
若未安装，见[环境要求](#环境要求)。若已安装仍报错，可使用更稳的等价写法：
```json
{
"command": "uv",
"args": ["tool", "run", "--from", "xianyu-mcp-server", "xianyu-mcp-server"]
}
```
### 2. Windows 报 `'uv' 不是内部或外部命令，也不是可运行的程序或批处理文件`
这是因为你的 Windows 系统**没有安装 uv**，或者安装后没有刷新 PATH 环境变量。
**解决方法**：
1. 在 PowerShell 中执行安装命令：
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
2. **关闭并重新打开** PowerShell / 终端窗口（这一步很关键，旧终端不会自动加载新 PATH）
3. 验证是否安装成功：
```powershell
uv --version
```
> 小提示：如果 Trae / Cherry Studio 等客户端已经打开，安装 uv 后最好也重启一下客户端，让它重新读取系统 PATH。
### 3. Trae 检测不到闲鱼 MCP
通常是以下原因之一：
- `mcpServers` 中没有注册当前服务
- `command` 或 `args` 写错（`uvx` 必须有 `--from xianyu-mcp-server xianyu-mcp-server`）
- uv / uvx 不在客户端运行时的 PATH 中，改用绝对路径或使用 `"command": "uv"` + `"tool", "run"` 写法
### 4. `validate_login` 返回 `FAIL_SYS_USER_VALIDATE`
通常表示当前 Cookie 已失效/不完整，或触发了更强风控校验。
建议优先走 `qr_login_generate/status/cookie` 重新获取；如果扫码后仍缺关键字段（例如 `_m_h5_tk` / `x5sec`）导致验证失败，需要按 `qr_login_status` 提示完成一次验证流程后再重试。
### 5. 修改 Cookie 后未生效
当前实现会在每次工具调用前重新读取环境变量或 `.env`。通常只要改的是：
- MCP 配置 `env` 中的 `XIANYU_COOKIE`
- 或 `XIANYU_COOKIE_FILE` 指向的实际文件
- 或当前工作目录下的 `.env`
下一次调用通常就会自动读取新值。
如果当前 MCP 客户端对服务进程做了缓存，重载客户端中的 MCP 服务会更稳妥。
### 6. `list_my_items` 报页数或每页条数超限
请把 `page_size` 调回默认值 `20`。
虽然工具层做了 `1 ~ 50` 的参数约束，但服务端对不同账号的实际限制可能更严格。
### 7. 部分商品无法重新上架
如果商品本身被平台限制为"仅支持 App 发布/编辑"，接口会返回：
- `FAIL_BIZ_PC_NOT_SUPPORT_PUBLISH_OR_EDIT`
目前实测结论是：
- 虚拟商品通常会命中这类 PC 端管控，无法通过当前 MCP 重新上架
- 支持 PC 编辑的实物商品，可以继续使用 `downshelf_item` / `reshelf_item`
## 相关文档
- CI/CD：[`./docs/ci-cd.md`](./docs/ci-cd.md)
- 底层项目说明：[`./third_party/pyxianyu/README.md`](./third_party/pyxianyu/README.md)
- 商品列表接口记录：[`./third_party/pyxianyu/docs/mtop_idle_web_xyh_item_list.md`](./third_party/pyxianyu/docs/mtop_idle_web_xyh_item_list.md)
- 商品下架接口记录：[`./third_party/pyxianyu/docs/mtop_taobao_idle_item_downshelf.md`](./third_party/pyxianyu/docs/mtop_taobao_idle_item_downshelf.md)
- 商品预发布检查接口记录：[`./third_party/pyxianyu/docs/mtop_idle_pc_idleitem_prepublish_check.md`](./third_party/pyxianyu/docs/mtop_idle_pc_idleitem_prepublish_check.md)
- 商品预取发布参数接口记录：[`./third_party/pyxianyu/docs/mtop_idle_pc_idleitem_preget.md`](./third_party/pyxianyu/docs/mtop_idle_pc_idleitem_preget.md)
- 商品编辑详情接口记录：[`./third_party/pyxianyu/docs/mtop_idle_pc_idleitem_edit_detail.md`](./third_party/pyxianyu/docs/mtop_idle_pc_idleitem_edit_detail.md)
- 商品编辑重发布接口记录：[`./third_party/pyxianyu/docs/mtop_idle_pc_idleitem_edit.md`](./third_party/pyxianyu/docs/mtop_idle_pc_idleitem_edit.md)
## 使用协议
本项目采用 `GNU General Public License v3.0` 协议。
- 允许：学习、修改、分发与再发布
- 要求：衍生作品在分发时需继续遵循 GPL v3.0 条款
- 提示：第三方依赖或子模块如有单独协议，以其各自协议为准
详细条款见 [`LICENSE`](./LICENSE)。
欢迎参与贡献，详见 [贡献指南](./CONTRIBUTING.md)。
## 免责声明
本项目仅供学习、技术研究与个人自动化实践使用，不用于任何商业用途。
闲鱼（Goofish）是阿里巴巴集团旗下的二手交易平台，本项目未获得阿里巴巴集团的任何授权或认可。本项目通过逆向分析闲鱼 Web 端接口实现自动化操作，可能违反闲鱼用户协议及相关平台规则。
使用本项目可能导致以下风险，包括但不限于：
- 账号被平台风控系统识别，触发功能限制、临时封禁或永久封号
- 账号内商品、资金、信用等资产受到冻结或扣减
- 因接口变更导致工具失效或数据异常
**项目开发者及贡献者不对任何人因使用本项目而产生的任何直接或间接损失承担责任，包括但不限于账号封禁、数据丢失、财产损失。**
使用本项目即表示你已阅读并理解上述风险，并同意自行承担一切后果。如果所在地区法律禁止此类使用，请立即停止使用并删除本项目。
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues