xianyu-mcp-server

基于 pyxianyu 封装的闲鱼 MCP 项目，用于把闲鱼商品、会话、消息发送等能力接入支持 MCP 的客户端。

风险提示：本项目仅供学习与技术研究使用。通过自动化手段操作闲鱼账号存在被平台风控、限制功能甚至封号的风险，使用者需自行承担一切后果。详见免责声明。

目录

• 鸣谢
• 项目概览
• 项目结构
• 功能特性
• 已知限制
• 环境要求
• 快速开始
• 客户端接入
• 推荐验证流程
• 常见问题
• 相关文档
• 使用协议
• 免责声明
• 贡献指南

鸣谢

• 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 / 工作流编排系统
• 作为后续自动客服、消息分发、店铺运维脚本的基础设施

项目结构

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 已开放这些工具：

用户信息相关用法

• 获取当前账号的个人信息（昵称/头像/地区等以接口返回为准）：调用 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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后关闭并重新打开终端（或刷新 PATH），然后验证：

uv --version

macOS / Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

快速开始

安装并启用

MCP 客户端配置（uvx 写法）

{
  "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 设置）：

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 配置：

{
  "mcpServers": {
    "xianyu-mcp-server": {
      "command": "uvx",
      "args": ["--from", "xianyu-mcp-server", "xianyu-mcp-server"],
      "env": {
        "XIANYU_COOKIE": "",
        "XIANYU_COOKIE_FILE": ""
      }
    }
  }
}

推荐优先使用 XIANYU_COOKIE_FILE 指向一个本地文件路径，避免把 Cookie 写进配置文件。

各客户端差异：

• 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 中可用：

uv --version

若未安装，见环境要求。若已安装仍报错，可使用更稳的等价写法：

{
  "command": "uv",
  "args": ["tool", "run", "--from", "xianyu-mcp-server", "xianyu-mcp-server"]
}

2. Windows 报 'uv' 不是内部或外部命令，也不是可运行的程序或批处理文件

这是因为你的 Windows 系统没有安装 uv，或者安装后没有刷新 PATH 环境变量。

解决方法：

1. 在 PowerShell 中执行安装命令：

   powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. 关闭并重新打开 PowerShell / 终端窗口（这一步很关键，旧终端不会自动加载新 PATH）
3. 验证是否安装成功：

   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
• 底层项目说明：./third_party/pyxianyu/README.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_idle_pc_idleitem_prepublish_check.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.md

使用协议

本项目采用 GNU General Public License v3.0 协议。

• 允许：学习、修改、分发与再发布
• 要求：衍生作品在分发时需继续遵循 GPL v3.0 条款
• 提示：第三方依赖或子模块如有单独协议，以其各自协议为准

详细条款见 LICENSE。

欢迎参与贡献，详见 贡献指南。

免责声明

本项目仅供学习、技术研究与个人自动化实践使用，不用于任何商业用途。

闲鱼（Goofish）是阿里巴巴集团旗下的二手交易平台，本项目未获得阿里巴巴集团的任何授权或认可。本项目通过逆向分析闲鱼 Web 端接口实现自动化操作，可能违反闲鱼用户协议及相关平台规则。

使用本项目可能导致以下风险，包括但不限于：

• 账号被平台风控系统识别，触发功能限制、临时封禁或永久封号
• 账号内商品、资金、信用等资产受到冻结或扣减
• 因接口变更导致工具失效或数据异常

项目开发者及贡献者不对任何人因使用本项目而产生的任何直接或间接损失承担责任，包括但不限于账号封禁、数据丢失、财产损失。

使用本项目即表示你已阅读并理解上述风险，并同意自行承担一切后果。如果所在地区法律禁止此类使用，请立即停止使用并删除本项目。