Skip to main content
Glama

闲鱼 MCP

基于 Playwright 的闲鱼自动化 MCP 服务,当前重点可用能力是搜索、登录状态检查、可发送会话筛选、消息发送/回读,以及基础商品分析。

本仓库来源:上游 A-utumn/xianyu-mcp(MIT)的完整导入, 由 @zhangjiabo522 做了可运行性修复。 详细安装步骤见 INSTALL.md,改动清单见文末「相对上游的改动」。

当前状态

  • 搜索链路已按当前 goofish.com 页面结构修复,可返回真实商品结果。

  • MCP 入口可直接调用 search_items、get_conversations、get_sendable_conversations、get_messages、send_message。

  • 消息模块已支持会话来源标记、可发送会话排序、上下文预热和商品上下文回填。

  • 分析模块当前已支持真实商品统计和竞品分析;销售、流量、热门商品排行仍有部分 TODO。

  • 发布模块仍有部分 TODO,不建议当成完整生产能力使用。

Related MCP server: Goofish MCP Server

快速开始

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/pip install "mcp>=1.0,<2"   # 必需:mcp 2.x 删除了 mcp.server.fastmcp
.venv/bin/playwright install chromium

.venv/bin/python scripts/login.py
.venv/bin/python scripts/check_status.py
.venv/bin/xianyu-mcp                  # 或 .venv/bin/python src/xianyu_mcp/server.py

扫码登录后,Cookie 会保存在 cookies/。完整说明见 INSTALL.md。

配置

参考 .env.example,环境变量前缀为 XIANYU_。

常用项:

XIANYU_HEADLESS=false
XIANYU_COOKIE_FILE=./cookies/default.json
XIANYU_USER_DATA_DIR=./user_data

主要工具

  • search_items: 搜索闲鱼商品

  • check_server_status: 检查 MCP 服务状态

  • publish_item: 发布商品(部分流程未完成)

  • get_conversations: 获取会话列表(支持 sendable_only / context_only 过滤)

  • get_sendable_conversations: 获取可发送会话(支持上下文预热)

  • get_unread_messages: 获取未读消息数

  • get_messages: 获取会话消息(返回 source、商品上下文等)

  • send_message: 发送消息

  • get_item_analytics: 获取单个商品的真实统计数据

  • analyze_competitors: 获取多个商品的竞品对比分析

测试

优先使用仓库内的脚本,而不是依赖 pytest:

python tests/quick_test.py
python tests/test_mcp_search.py
python tests/test_precise_search.py
python tests/test_message_tools.py
python tests/test_analytics_tools.py
python tests/test_all.py

测试脚本说明见 tests/README.md。

目录

  • src/xianyu_mcp/: 主代码

  • scripts/: 登录和状态检查脚本

  • tests/: 保留的手动测试脚本

  • examples/: 示例

说明

本项目仅供学习和自动化研究使用。请自行控制访问频率,并遵守目标平台规则。

相对上游的改动

  1. stdio 入口修复:main_async() 原来只 await stop_event.wait(),从未启动 transport,MCP 客户端无法连接;改为 await mcp.run_stdio_async()。

  2. 依赖上限:mcp>=1.0.0 → mcp>=1.0.0,<2(mcp 2.x 已移除 mcp.server.fastmcp,会直接 ImportError)。

  3. .env.example 修正:前缀 XIANIU_ 拼错(代码读 XIANYU_), 键名重复为 XIANYU_XIANIU_URL,URL 指向过期的 2.taobao.com; 已统一为 XIANYU_XIANYU_URL / XIANYU_XIANYU_MOBILE_URL 并指向 goofish.com。

  4. 补充 LICENSE(MIT,含上游版权声明)与 INSTALL.md(安装/验证记录)。

  5. tests/README.md 链接从本机绝对路径改为相对路径。

Available Tools

18 tools
analyze_competitorsC

分析竞品商品

Args: item_ids: 竞品商品 ID 列表

Returns: 竞品分析结果

Inputs: item_ids (required).

check_server_statusB

检查服务器状态

Inputs: no named parameters.

delete_itemA

下架商品(默认)或在明确允许时删除商品

Args: item_id: 商品 ID force_delete: 当无法下架时是否尝试删除 dry_run: 是否仅检查按钮和确认弹窗,不真正执行

Returns: 处理结果

Inputs: item_id (required), dry_run, force_delete.

edit_itemA

编辑已发布商品

Args: item_id: 商品 ID updates: 更新内容,可包含 title/description/price/location/condition/delivery/images dry_run: 是否仅试填,不真正提交

Returns: 编辑结果

Inputs: item_id (required), updates (required), dry_run.

generate_reportC

生成综合分析报告

Args: days: 统计天数

Returns: 报告数据

Inputs: days.

get_conversationsC

获取会话列表

Args: limit: 数量限制 sendable_only: 是否仅返回可发送会话 context_only: 是否仅返回已有商品上下文的会话

Returns: 会话列表和状态

Inputs: limit, context_only, sendable_only.

get_item_analyticsC

获取商品统计数据

Args: item_id: 商品 ID

Returns: 商品统计数据

Inputs: item_id (required).

get_messagesC

获取指定会话的消息列表

Args: conversation_id: 会话 ID limit: 消息数量限制

Returns: 消息列表和状态

Inputs: conversation_id (required), limit.

get_sales_analyticsC

获取销售统计

Args: days: 统计天数

Returns: 销售统计数据

Inputs: days.

get_sendable_conversationsC

获取可发送会话列表

Args: limit: 返回数量限制 warm_context: 是否尝试预热前几个会话的商品上下文

Returns: 可发送会话列表和状态

Inputs: limit, warm_context.

get_top_itemsC

获取热门商品排行

Args: limit: 返回数量 sort_by: 排序方式 (sales, views, wants)

Returns: 商品列表

Inputs: limit, sort_by.

get_traffic_analyticsC

获取流量统计

Args: days: 统计天数

Returns: 流量统计数据

Inputs: days.

get_unread_messagesB

获取未读消息数

Returns: 未读消息状态

Inputs: no named parameters.

helloB

测试工具 - 验证 MCP 服务器是否正常运行

Inputs: name (required). Returns: result

list_my_itemsC

列出当前账号在个人主页可管理的商品

Args: limit: 数量限制

Returns: 商品列表

Inputs: limit.

publish_itemB

发布闲鱼商品

Args: title: 标题(最多 20 字) description: 描述(最多 1000 字) price: 价格 images: 图片路径列表 category: 分类 location: 地区 condition: 新旧程度 delivery: 配送方式 dry_run: 是否仅预检查表单,不真正提交发布

Returns: 发布结果 {"success": bool, "item_id": str, "message": str}

Inputs: price (required), title (required), images (required), description (required), +5 more.

search_itemsB

搜索闲鱼商品(带错误恢复)

Args: keyword: 搜索关键词 price_min: 最低价格 price_max: 最高价格 location: 地区筛选 sort_by: 排序方式 (default, price_asc, price_desc, sales) limit: 返回数量限制

Returns: 商品列表

Inputs: keyword (required), limit, sort_by, location, +2 more.

send_messageC

发送消息

Args: user_id: 用户 ID content: 消息内容

Returns: 发送结果

Inputs: content (required), user_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 18 tools

    Disambiguation3/5

    Most tools target distinct resources or actions, but several overlaps create ambiguity: get_sendable_conversations largely duplicates get_conversations with sendable_only=true, hello overlaps with check_server_status, generate_report overlaps with get_sales_analytics, and get_top_items overlaps with search_items when sorted by sales.

    Naming Consistency4/5

    The tool set is consistently snake_case and mostly follows a verb_noun or get_noun pattern. The only notable outlier is 'hello', while names like check_server_status, search_items, and get_traffic_analytics fit the convention.

    Tool Count4/5

    18 tools is slightly above the typical ideal range, but the server spans multiple subdomains: health checks, item search/publishing, messaging, and analytics. The count is mostly justified, though a few redundant tools inflate it.

    Completeness4/5

    The surface covers item CRUD, search, messaging, and several analytics views, which is strong for this domain. Minor gaps remain, such as a dedicated get_item detail endpoint and any order/transaction management, but core workflows are covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      An MCP server that automates Xianyu marketplace operations through Playwright, allowing users to manage listings and conduct market research via natural language. It features integrated tools for generating AI-powered product descriptions and cover images using DashScope.
      11
      26
      -
    • A
      license
      B
      quality
      A
      maintenance
      MCP server for automating Xianyu (Goofish) marketplace operations: publish, manage items, handle IM messages, and more via CLI or AI agents.
      17
      802 PyPI
      487
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables automating buyer-side workflows on Xianyu (Goofish) by searching products, sending individual or batch price inquiries, and retrieving seller responses through MCP tools.
      1
      MIT