Token导航 LogoToken导航TokenDH.com
中转站排行榜
Xianyu MCP logo
浏览器工具未说明官方级别未说明来源级核验

Xianyu MCP

MCP Server

基于Go + Gin + MCP SDK + Rod的闲鱼自动化服务，提供HTTP API和MCP Tools，支持AI Agent或业务系统调用。

工具数

41

提示词数

0

GitHub Stars

5

资源数

0
浏览器自动化GoAPI封装

安装说明

本站只整理中文说明和来源信息，不托管安装包，也不代用户安装。

GitHub

作者 / 组织

yy945635407

提供方

yy945635407

最后核验

2026/5/17 20:23

快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

详细介绍

xianyu-mcp

基于 Go + Gin + MCP SDK + Rod 的闲鱼自动化服务，提供：

  • 标准 HTTP API（/api/v1/*）
  • MCP Streamable HTTP（/mcp）

项目目标是把闲鱼网页操作能力封装成可编排的 API / MCP Tools，便于 AI Agent 或业务系统直接调用。

AI Agent 专用说明见：AI_USAGE.md

1. 软件架构

1.1 分层架构

            Client / Agent
         (HTTP or MCP Client)
                    |
         +----------+----------+
         |   Gin Router        |
         | /health /api/v1 /mcp|
         +----------+----------+
                    |
             AppServer/Handlers
                    |
              XianyuService
          +---------+---------+
          |                   |
    Local JSON Stores    Rod Browser Session
     (状态/幂等/知识)       (单例复用浏览器)
          |                   |
          +---------+---------+
                    |
            xianyu/* Action
       (登录/消息/订单/发布等网页自动化)

1.2 模块职责

层关键文件职责
入口层main.go, app_server.go解析启动参数、初始化服务、优雅退出
路由层routes.go, middleware.go注册 HTTP/MCP 路由、CORS、panic 恢复
协议适配层handlers_api.go, mcp_handlers.go, mcp_server.goHTTP/MCP 参数绑定、调用服务层、统一返回格式
业务编排层service.go参数兜底、重试、幂等、会话策略、知识匹配、自动上下文
自动化动作层xianyu/*.go具体网页操作（登录、消息、发布、订单、收藏、社区等）
状态持久层im_*_store.go, storage_paths.go本地 JSON 存储事件、会话状态、发送记录、知识库
浏览器封装层browser/browser.go, configs/*, cookies/*浏览器实例配置、代理、Cookie 读写、无头模式控制

1.3 关键设计点

  1. 双协议入口
  • HTTP 供业务系统直接接入。
  • MCP 供 Agent 通过 Tool 调用。
  1. 浏览器单例复用
  • service.go 内通过 sharedBrowserInst + refCount 复用浏览器，减少频繁启动开销。
  1. 本地状态持久化
  • 事件流、会话状态、消息发送幂等记录、知识库都落盘到 data/*.json（可通过 DATA_DIR 改目录）。
  1. 消息发送安全控制
  • 发送前检查会话模式（bot/human）和会话锁。
  • client_msg_id 做幂等，重复请求不会重复发送。
  1. 增量事件流
  • 从会话列表生成增量事件（since_id 游标）并支持阻塞等待接口 wait_im_events。
  1. 知识库上下文匹配
  • 支持关键词 + 商品上下文 + 订单状态匹配。
  • 支持 auto_context 按用户名自动补全上下文（含缓存与刷新节流）。

2. 能力总览

当前已注册 40 个 MCP Tools，HTTP 侧提供同等能力。

2.1 登录与基础

  • check_login_status
  • get_login_qrcode
  • delete_cookies
  • search_items

2.2 消息与客服自动化

  • list_conversations
  • get_messages
  • pull_im_events
  • wait_im_events
  • get_im_session_state
  • list_im_session_states
  • set_im_session_state
  • mark_im_session_read
  • send_message
  • upsert_im_knowledge
  • list_im_knowledge
  • delete_im_knowledge
  • match_im_knowledge

2.3 发布与订单

  • publish_item
  • list_orders
  • remind_ship
  • ship_order
  • ship_with_logistics
  • confirm_receipt
  • review_order
  • handle_refund

2.4 收藏、我的商品、商品详情

  • list_collections
  • cancel_favorite
  • manage_collection_group
  • list_my_items
  • edit_my_item
  • shelf_my_item
  • delete_my_item
  • get_item_detail
  • favorite_item
  • chat_item
  • buy_item

2.5 账号与社区

  • get_account_security
  • get_community_feed
  • interact_community
  • get_customer_service
  • open_customer_service

3. 目录结构

xianyu-mcp/
├── main.go                  # 服务启动入口
├── app_server.go            # HTTP Server 生命周期
├── routes.go                # 路由注册
├── handlers_api.go          # HTTP 处理器
├── mcp_server.go            # MCP Tool 注册
├── mcp_handlers.go          # MCP 处理器
├── service.go               # 核心业务编排
├── im_event_store.go        # 增量事件存储
├── im_session_store.go      # 会话状态存储
├── im_send_record_store.go  # 消息幂等记录存储
├── im_knowledge_store.go    # 知识库存储
├── storage_paths.go         # DATA_DIR 路径管理
├── browser/                 # 浏览器初始化
├── cookies/                 # Cookie 读写
├── configs/                 # 运行配置
├── cmd/login/               # 手动登录工具
├── cmd/explore/             # 页面入口探索工具
├── xianyu/                  # 闲鱼动作实现层
├── AI_USAGE.md              # AI/Agent 调用指南
└── README.md

4. 快速开始

4.1 环境要求

  • Go 1.24+
  • 本机可用 Chrome/Chromium
  • 可访问 https://www.goofish.com/

4.2 安装依赖

go mod tidy

4.3 首次登录（必须）

go run ./cmd/login

说明：

  • 会启动可见浏览器（非 headless）。
  • 扫码后会将 Cookie 保存到 cookies.json（或 COOKIES_PATH 指定路径）。

4.4 启动服务

go run . -headless=false -port=:18061

启动后可用地址：

  • 健康检查：GET http://127.0.0.1:18061/health
  • HTTP API：http://127.0.0.1:18061/api/v1
  • MCP：http://127.0.0.1:18061/mcp

5. 配置说明

5.1 启动参数

参数默认值说明
-headlesstrue是否无头模式运行浏览器
-bin""浏览器二进制路径（优先于自动查找）
-port:18061HTTP 服务监听地址

5.2 环境变量

变量默认值说明
ROD_BROWSER_BIN空浏览器路径（等价于 -bin）
XIANYU_PROXY空浏览器代理，如 http://user:pass@host:port
COOKIES_PATHcookies.jsonCookie 文件路径
DATA_DIRdata本地状态存储目录
XIANYU_IM_SCAN_INTERVAL_MS15000IM 轮询最小间隔（毫秒，最小 1000）
XIANYU_AUTOCTX_REFRESH_SEC180自动上下文刷新间隔（秒，最小 30）
XIANYU_AUTOCTX_TTL_SEC900自动上下文缓存 TTL（秒，最小 60）

6. 本地数据文件

默认在 data/ 目录下生成：

文件用途
im_events.jsonIM 增量事件流（since_id 游标）
im_session_states.json会话模式、人工接管、锁、已读时间
im_send_records.jsonclient_msg_id 幂等记录
im_knowledge.json智能客服知识库

7. HTTP 使用方法与示例

7.1 返回格式

成功：

{
  "success": true,
  "data": {},
  "message": "..."
}

失败：

{
  "error": "...",
  "code": "...",
  "details": "..."
}

7.2 基础验证

# 健康检查
curl 'http://127.0.0.1:18061/health'

# 登录状态
curl 'http://127.0.0.1:18061/api/v1/login/status'

# 获取二维码（未登录时）
curl 'http://127.0.0.1:18061/api/v1/login/qrcode'

# 重置登录态
curl -X DELETE 'http://127.0.0.1:18061/api/v1/login/cookies'

7.3 搜索商品

curl 'http://127.0.0.1:18061/api/v1/search?keyword=iphone&limit=5'

7.4 IM 自动回复闭环（推荐顺序）

  1. 拉取增量事件
curl 'http://127.0.0.1:18061/api/v1/im/events?since_id=0&limit=50&scan_limit=30'
  1. 阻塞等待增量（守护进程推荐）
curl 'http://127.0.0.1:18061/api/v1/im/events/wait?since_id=0&limit=50&scan_limit=30&timeout_sec=30&poll_ms=1200'
  1. 查看会话消息
curl 'http://127.0.0.1:18061/api/v1/im/messages?username=发韧的树枝&limit=30'
  1. 查询会话状态（防误发）
curl 'http://127.0.0.1:18061/api/v1/im/session/state?username=发韧的树枝'
  1. 发送消息（带幂等 ID）
curl -X POST 'http://127.0.0.1:18061/api/v1/im/send' \
  -H 'Content-Type: application/json' \
  -d '{
    "username":"发韧的树枝",
    "message":"你好，这边已收到",
    "client_msg_id":"auto-10001-a1b2c3d4",
    "max_retries":2,
    "force":false,
    "limit":20
  }'
  1. 标记会话已读
curl -X POST 'http://127.0.0.1:18061/api/v1/im/session/mark_read' \
  -H 'Content-Type: application/json' \
  -d '{"username":"发韧的树枝","limit":30}'

7.5 知识库管理与匹配

# 新增/更新知识
curl -X POST 'http://127.0.0.1:18061/api/v1/im/kb/upsert' \
  -H 'Content-Type: application/json' \
  -d '{
    "title":"价格解释",
    "keywords":["最低多少","还能便宜吗","包邮吗"],
    "answer":"你好，这个价格已经是活动价，支持包邮。",
    "order_statuses":["未下单","已拍下"],
    "priority":10
  }'

# 列表查询
curl 'http://127.0.0.1:18061/api/v1/im/kb/list?query=便宜&limit=20'

# 匹配知识（支持 auto_context）
curl -X POST 'http://127.0.0.1:18061/api/v1/im/kb/match' \
  -H 'Content-Type: application/json' \
  -d '{
    "message":"还能便宜吗？包邮吗",
    "username":"发韧的树枝",
    "top_k":3,
    "auto_context":true
  }'

7.6 发布闲置

# 仅填表校验（不提交）
curl -X POST 'http://127.0.0.1:18061/api/v1/publish/item' \
  -H 'Content-Type: application/json' \
  -d '{
    "images": ["/abs/path/a.jpg"],
    "description": "九成新，正常使用",
    "price": "88",
    "original_price": "120",
    "shipping_type": "包邮",
    "location_keyword": "成都",
    "submit": false
  }'
建议先 submit=false 验证字段与页面元素，再改为 submit=true 真正发布。

7.7 订单能力

# 查询订单
curl 'http://127.0.0.1:18061/api/v1/orders/list?tab=全部&limit=20'

# 提醒卖家发货
curl -X POST 'http://127.0.0.1:18061/api/v1/orders/remind_ship' \
  -H 'Content-Type: application/json' \
  -d '{"order_keyword":"车展门票","seller_name":"后晋登山的大挣"}'

# 会话触发去发货
curl -X POST 'http://127.0.0.1:18061/api/v1/orders/ship' \
  -H 'Content-Type: application/json' \
  -d '{"username":"发韧的树枝"}'

# 带物流发货
curl -X POST 'http://127.0.0.1:18061/api/v1/orders/ship_with_logistics' \
  -H 'Content-Type: application/json' \
  -d '{"username":"发韧的树枝","company":"中通","tracking_no":"YT123456789"}'

# 确认收货
curl -X POST 'http://127.0.0.1:18061/api/v1/orders/confirm_receipt' \
  -H 'Content-Type: application/json' \
  -d '{"order_keyword":"耳机"}'

# 评价订单
curl -X POST 'http://127.0.0.1:18061/api/v1/orders/review' \
  -H 'Content-Type: application/json' \
  -d '{"order_keyword":"耳机","score":5,"content":"发货快，描述一致"}'

# 退款处理
curl -X POST 'http://127.0.0.1:18061/api/v1/orders/refund' \
  -H 'Content-Type: application/json' \
  -d '{"order_keyword":"耳机","action":"detail"}'

7.8 收藏、我的商品、商品详情

# 收藏夹列表
curl 'http://127.0.0.1:18061/api/v1/collections/list?limit=20'

# 取消收藏（关键词或 item_ref 二选一）
curl -X POST 'http://127.0.0.1:18061/api/v1/collections/cancel' \
  -H 'Content-Type: application/json' \
  -d '{"keyword":"iPhone 13"}'

# 我的商品列表
curl 'http://127.0.0.1:18061/api/v1/my/items?tab=在售&limit=20'

# 商品详情
curl 'http://127.0.0.1:18061/api/v1/item/detail?item_ref=https://www.goofish.com/item?id=xxxxxxxx'

# 商品聊一聊
curl -X POST 'http://127.0.0.1:18061/api/v1/item/chat' \
  -H 'Content-Type: application/json' \
  -d '{"item_ref":"https://www.goofish.com/item?id=xxxxxxxx","message":"你好，还在吗"}'

8. MCP 接入说明

8.1 MCP 地址

  • http://127.0.0.1:18061/mcp

8.2 说明

  • 基于 go-sdk 的 Streamable HTTP。
  • Tool 输出主体通常在 content[].text，多数是 JSON 字符串（客户端需再解析一次）。
  • 建议调用策略见 AI_USAGE.md（已包含消息自动回复最小闭环与风控建议）。

9. HTTP 路由清单

9.1 基础

  • GET /health
  • GET /api/v1/login/status
  • GET /api/v1/login/qrcode
  • DELETE /api/v1/login/cookies

9.2 搜索

  • GET|POST /api/v1/search

9.3 IM / 客服

  • GET /api/v1/im/conversations
  • GET|POST /api/v1/im/messages
  • GET|POST /api/v1/im/events
  • GET|POST /api/v1/im/events/wait
  • GET /api/v1/im/session/state
  • GET /api/v1/im/session/states
  • POST /api/v1/im/session/state
  • POST /api/v1/im/session/mark_read
  • POST /api/v1/im/send
  • GET /api/v1/im/kb/list
  • POST /api/v1/im/kb/upsert
  • POST /api/v1/im/kb/delete
  • POST /api/v1/im/kb/match

9.4 发布与订单

  • POST /api/v1/publish/item
  • GET /api/v1/orders/list
  • POST /api/v1/orders/remind_ship
  • POST /api/v1/orders/ship
  • POST /api/v1/orders/ship_with_logistics
  • POST /api/v1/orders/confirm_receipt
  • POST /api/v1/orders/review
  • POST /api/v1/orders/refund

9.5 收藏 / 我的商品 / 商品详情

  • GET /api/v1/collections/list
  • POST /api/v1/collections/cancel
  • POST /api/v1/collections/groups/manage
  • GET /api/v1/my/items
  • POST /api/v1/my/items/edit
  • POST /api/v1/my/items/shelf
  • POST /api/v1/my/items/delete
  • GET /api/v1/item/detail
  • POST /api/v1/item/favorite
  • POST /api/v1/item/chat
  • POST /api/v1/item/buy

9.6 账号与社区

  • GET /api/v1/account/security
  • GET /api/v1/community/feed
  • POST /api/v1/community/interact
  • GET /api/v1/customer/service
  • POST /api/v1/customer/open

10. 调试与排障

10.1 页面入口探索

go run ./cmd/explore

用于快速扫描当前登录态下可见入口，辅助扩展新能力。

10.2 常见问题

  1. conversation not found
  • 先 list_conversations 核对 username，避免昵称不一致。
  1. UI not ready
  • 页面结构抖动导致元素未就绪，可重试并降低并发。
  1. client_msg_id already used with different payload
  • 同一个 client_msg_id 发送了不同消息体，需更换 ID。
  1. 物流发货返回 requires_app=true
  • 当前网页端能力受限，需转闲鱼 App 完成。
  1. 端口冲突
  • 改端口启动：go run . -port=:18062

11. 安全建议

  • 当前服务默认无鉴权、CORS 允许 *，请仅在受信内网使用。
  • 不建议直接暴露公网；如需对外，请在网关层增加鉴权与访问控制。
  • 生产使用建议配合审计日志、调用限流和人工兜底策略。

目录标签

目录标签

浏览器自动化GoAPI封装闲鱼自动化本地部署网页自动化MCPToolsAIAgent集成

接入字段

传输方式（transport，传输协议）

未说明

鉴权方式（authType，认证方式）

session

工具数量（toolCount，工具数）

41

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

未说明session部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

仍需确认：installCommand

来源信息

xianyu-mcp logo

MCP World

mcpworld.com

/detail/93463f342a7495fd5b3955d8a7dec100

基于Go + Gin + MCP SDK + Rod的闲鱼自动化服务，提供HTTP API和MCP Tools，支持AI Agent或业务系统调用。

继续浏览同类 MCP

更多浏览器工具 MCP（2,803）返回 MCP 目录

上一个 MCP

Xhs Pro MCP

基于Playwright浏览器和MCP协议的小红书数据采集服务，支持飞书多维表格同步，提供数据采集、媒体下载、互动操作和内容发布等功能。

下一个 MCP

Xiaohongshu MCP Python

小红书MCP服务器的Python实现，提供登录管理、内容浏览、互动功能、用户信息查看和内容发布等核心功能。