闲鱼MCP服务
让 AI 自动管你的闲鱼店铺：xianyu-mcp-server 开源项目体验
每天手动上架、回消息、改价格、查竞品太费时间？这个开源项目把闲鱼能力封装成标准 MCP 工具，让 Trae、Claude Desktop、Cursor、VS Code、Cherry Studio 这类 AI 客户端直接操作你的闲鱼账号。
20 个 MCP 工具 | 5 大客户端 | 扫码登录 | 风控护栏 |uvx即用
GitHub 仓库：DoLovya/xianyu-mcp-server
能干什么：你发一句话，AI 直接替你操作闲鱼
接入之后，你在 AI 客户端里直接说自然语言就行。
“把我店里所有价格低于 50 的商品下架”
AI 会自动拉取你的全部商品，筛选符合条件的条目，然后逐个执行下架。这个过程不是简单暴力地一口气猛点接口，而是带着项目内置的风控护栏去跑，自动控制写操作间隔和重试节奏。
“看看最近有没有人给我发消息，有的话帮我回一下”
AI 可以先拉会话列表，再读指定会话历史，最后调用发消息工具回复买家。对卖家来说，这一步已经很接近“AI 客服”。
“帮我搜一下闲鱼上有没有二手 Switch，按最新发布排序”
AI 会直接调用搜索接口，把最新发布的商品列表整理出来，不用你再手动打开 App 一页页翻。
这不是 PPT 式设想，而是当前仓库已经封装好的 MCP 工具能力。你不需要自己研究 Cookie 签名、接口参数、消息协议，AI 客户端会直接调用这些工具。
现在有哪些能力：20 个 MCP 工具，覆盖卖家高频场景
当前xianyu-mcp-server已开放20 个 MCP 工具，大致分成 5 组。
1. 登录与登录态维护
| 工具 | 说明 |
|---|---|
validate_login | 校验当前 Cookie 是否有效 |
refresh_login | 刷新当前登录态 |
qr_login_generate | 生成扫码登录二维码 |
qr_login_status | 查询扫码登录状态，必要时返回验证信息 |
qr_login_cookie | 在扫码成功后提取完整 Cookie |
qr_login_save_env | 把扫码得到的 Cookie 直接写回.env |
这套链路最大的价值是：第一次使用时可以不手动抓 Cookie。把.env留空启动，项目就能引导你扫码登录，成功后还可以直接写回环境文件。
2. 商品搜索、详情与店铺管理
| 工具 | 说明 |
|---|---|
search_items | 按关键词搜索闲鱼商品，支持分页与排序 |
get_item_detail | 获取指定商品详情 |
get_item_edit_detail | 获取商品在 PC 编辑页的详情 |
list_my_items | 自动翻页拉取当前账号下全部商品 |
downshelf_item | 下架指定商品 |
reshelf_item | 通过 PC 编辑重发布链路重新上架商品 |
edit_item | 编辑商品标题、价格、描述等信息 |
publish_physical_item | 发布新的实体商品，支持自动上传图片 |
对于卖家来说，这一组已经能覆盖“查商品、改商品、上下架、发新品”这些最常用动作。
3. 用户信息与会话消息
| 工具 | 说明 |
|---|---|
get_my_profile | 获取当前登录账号的个人资料信息 |
list_conversations | 拉取最近会话列表 |
list_conversation_messages | 获取指定会话历史消息 |
send_text_message | 发送文本消息 |
send_image_message | 发送图片消息 |
这让项目不只是“自动上下架工具”，而是已经具备向客服和卖家助手方向继续扩展的基础。
4. 媒体上传
| 工具 | 说明 |
|---|---|
upload_media | 上传本地文件或 URL 素材，返回可复用媒体链接 |
这个能力既能给publish_physical_item服务，也能给图片消息或后续编辑商品时复用。
5. 风控友好的调用护栏
这部分不是单独的 MCP 工具，但恰恰是项目很有价值的地方。仓库内已经实现了请求护栏：
- 读写分离限速：读操作和写操作使用不同节奏
- 写操作串行化：避免多条写请求并发触发风控
- 指数退避：遇到可疑错误自动退避重试
- 冷却机制：识别强风控信号后主动进入冷却
自动化不等于无脑猛调接口，这套护栏决定了它更适合长期真实使用。
为什么这个项目值得关注：不是脚本堆砌，而是标准 MCP 接入
价值一：标准 MCP 协议，主流 AI 客户端都能接
项目基于标准 MCP（Model Context Protocol）实现，不绑定某一个 AI 产品。
| 客户端 | 接入方式 |
|---|---|
| Trae | 项目内配置.trae/mcp.json |
| Claude Desktop | 写入claude_desktop_config.json |
| Cursor | 配置.cursor/mcp.json |
| VS Code | 配置.vscode/mcp.json |
| Cherry Studio | UI 中新增 MCP 服务，可选stdio或 HTTP |
对用户来说，这意味着你只需要把服务跑起来，接入哪个 AI 客户端都比较顺手。
价值二：扫码登录友好，第一次使用门槛低
很多自动化项目最劝退的一步，就是让你自己抓 Cookie。这个项目把扫码登录能力做成了完整链路：
- 生成二维码
- 手机扫码确认
- 查询登录状态
- 拿到完整 Cookie
- 一键写回
.env
如果遇到人脸验证或额外风控，工具也会把状态暴露出来，而不是让你只看到一个模糊的失败提示。
价值三：从“会调接口”进化到“可接入真实工作流”
很多项目把接口打通就结束了，但 MCP 项目的价值在于，它天然适合接到 Agent 工作流里。比如：
- 用 AI 批量整理店铺商品
- 用 AI 自动做竞品搜索
- 用 AI 帮你回复买家
- 后续继续扩展成消息监听 + 自动回复 Worker
这类能力一旦接入标准 MCP，复用成本会低很多。
三步快速上手
这里分两种方式：直接使用，以及源码开发。
方式一：uvx直接启动（推荐）
如果你只是想先体验，最省事的方式是：
uvx xianyu-mcp如果想以 HTTP 模式启动：
uvx xianyu-mcp--http默认地址是：
http://localhost:8000/mcp方式二：源码开发模式
如果你要改代码、联调或本地开发，再 clone 仓库：
gitclone https://github.com/DoLovya/xianyu-mcp-server.gitcdxianyu-mcp-servercp.env.example .env uvsyncuv run xianyu-mcp这里的third_party/pyxianyu更适合作为开发调试用源码依赖理解，而不是普通使用者必须手动维护的安装步骤。
没有 Cookie 也能先跑起来
.env可以先留空。项目支持扫码登录流程，首次启动时会引导你完成登录，并把 Cookie 写回本地环境文件。对第一次上手非常友好。
Trae / Cursor / Claude Desktop 怎么接
大多数 MCP 客户端都使用stdio模式。对源码开发场景，推荐直接让客户端用工作区里的uv环境启动服务。
Trae 项目级配置示例：
{"mcpServers":{"xianyu-mcp-server":{"command":"uv","args":["--directory","${workspaceFolder}","run","xianyu-mcp"]}}}如果你不打算 clone 仓库，而是想直接跑已安装的包，也可以使用：
{"mcpServers":{"xianyu-mcp-server":{"command":"uvx","args":["xianyu-mcp"]}}}几个关键点：
- Trae / Cursor / Claude Desktop / VS Code一般优先走
stdio - Cherry Studio除了
stdio，也可以接 HTTP 模式 - 源码开发场景优先使用
uv --directory ${workspaceFolder} run xianyu-mcp - 普通试用场景优先使用
uvx xianyu-mcp
实战场景：这些事 AI 已经能帮你做
场景一：批量店铺运维
“把我店里所有价格低于 100 的商品都下架”
AI 会先调用list_my_items拉完整个商品列表，再筛选，再逐个调用downshelf_item。这个流程对卖家特别友好，因为它避免了你自己在 App 里重复机械操作。
场景二：竞品搜索与价格观察
“搜一下闲鱼上二手 Switch，按最新发布排序”
AI 直接调用search_items，把最新发布结果整理出来。你后续还可以继续追问：
- 哪些价格更低
- 哪些卖家在同城
- 哪些成色描述更好
场景三：AI 帮你做客服
“看看最近有没有人问我商品问题，有的话帮我回一下”
这个流程会串起：
list_conversationslist_conversation_messagessend_text_message/send_image_message
对于经常被买家反复问同类问题的卖家来说，这已经很接近“把客服交给 AI 打底处理”。
场景四：一键发布新品
“帮我发一个九成新 Kindle Oasis，价格 800，配这几张图”
AI 可以先上传图片，再调用publish_physical_item完成发布。对经常在电脑端整理素材的人来说，这比在手机里反复填表单顺手很多。
工程质量：它已经不是玩具项目了
当前仓库能核实到的工程状态大致如下：
| 指标 | 当前情况 |
|---|---|
| MCP 工具数 | 20 |
| Python 测试矩阵 | 3.11 / 3.12 / 3.13 |
| 测试文件 | 8 |
| 单元测试 | 24 |
| 包入口 | xianyu-mcp |
| 依赖管理 | uv |
| CI | GitHub Actions 持续集成 |
更关键的是，项目现在已经不只是“本地脚本 + 子模块硬拼装”的状态，而是在往标准 Python 包依赖和标准 MCP 接入方式上收敛。这意味着：
- 使用者安装成本更低
- IDE / AI 客户端接入更顺
- 后续发布到 PyPI、通过
uvx启动这条路也更清晰
已知限制和接下来的方向
先说目前的边界，这样更真实。
当前已知限制
- 虚拟商品通常受闲鱼 PC 端发布/编辑限制，当前无法稳定走
reshelf_item重新上架 - 常驻消息监听与自动回复 Worker 还没有 MCP 化
- 语音、视频类消息工具还没开放出来
接下来最值得期待的方向
- 消息监听和自动回复拆成独立 Worker
- 更多商品类型支持
- 面向卖家的数据分析能力
- 更完善的多客户端接入文档
所以这个项目现在最适合的定位是：已经能用、适合接入 AI 工作流、仍在持续扩展的闲鱼 MCP 基础设施。
适合谁用
如果你属于下面几类人，这个项目会特别有感觉：
- 经常在闲鱼卖二手、想减少重复操作的人
- 喜欢把日常工作流交给 AI 自动化的人
- 正在研究 MCP 落地案例的人
- 想做 AI 客服、AI 店铺助手、Agent 自动运维的人
它不是“一个只能演示的 Demo”，而是已经具备继续往真实卖家工作流里长的基础。
开始用起来
先用最短命令跑起来：
uvx xianyu-mcp如果你要在工作区里和 Trae 一起联调，就用：
uv--directory${workspaceFolder}run xianyu-mcpGitHub 仓库：DoLovya/xianyu-mcp-server
如果你最近正好在折腾 AI 自动化、MCP 或卖家工具，这个项目很值得实际跑一遍。因为它不是单纯“能连上接口”，而是已经把登录、商品、消息、上传、风控这些关键拼图接起来了。
风险提示与免责声明
本项目仅供学习、技术研究与个人自动化实践使用，不用于任何商业用途。闲鱼（Goofish）是阿里巴巴集团旗下的二手交易平台，本项目未获得平台授权或认可。
项目通过逆向分析闲鱼 Web 端接口实现自动化操作，使用过程中可能触发平台风控、功能限制、临时封禁或永久封号等后果。项目开发者与贡献者不对因使用本项目产生的直接或间接损失负责。使用前请自行评估风险，并遵守所在地区法律法规与平台规则。