xhs_searchMcp

还在手动打开小红书、输入关键词、点开筛选、寻找高赞笔记，再一张张保存图片、复制标题和正文？

把关键词交给 xhs_searchMcp 就够了。它会自动完成搜索与筛选，找到“图文 · 最多点赞”的第一篇笔记，并将标题、正文、作者、链接和图片整理成可以直接交给 AI 或程序使用的结构化数据。

xhs_searchMcp 是一个基于 TypeScript、Playwright 和 MCP 的小红书图文笔记采集工具。它既可以作为 MCP Server 被 Codex、Claude Desktop 等客户端调用，也可以作为普通命令行脚本（Cli）独立运行。

它能做什么？

只需传入一个关键词：

露营装备

xhs_searchMcp 会自动执行：

打开小红书
  → 搜索关键词
  → 打开“筛选”面板
  → 选择“图文”
  → 选择“最多点赞”
  → 打开第一篇笔记
  → 提取标题、正文、作者和图片
  → 下载图片并生成 result.json

主要特性：

• 🔥 自动寻找指定关键词下“最多点赞”的图文笔记
• 📝 结构化提取标题、正文、作者和笔记链接
• 🖼️ 提取图片原始地址，并可自动下载到本地
• 🤖 提供标准 MCP 工具，可直接加入 AI 工作流
• ⌨️ 同时提供 CLI，无需 MCP 客户端也能使用
• 🔐 使用独立浏览器配置，不读取或修改日常 Chrome Cookie
• 🧯 操作失败时返回明确错误码并保存现场截图

环境要求

• Node.js 18.18 或更高版本（推荐 Node.js 20/22）
• npm
• Windows、macOS 或 Linux 桌面环境
• 有效的小红书账号登录状态

快速开始

1. 安装chromium（建议开启代理）

npm install
npx playwright install chromium

2. 初始化专用浏览器（进入项目根目录）

首次使用或登录状态失效时执行：

npm run build
npm.cmd run setup-profile

程序会打开一个专用于 xhs_searchMcp 的 Chromium：

1. 在浏览器中扫码登录小红书。
2. 完成后回到终端按回车。

初始化过程没有扫码超时限制，可以从容完成操作。登录数据保存在项目的 browser-profile 目录中，与日常使用的 Google Chrome 完全隔离。

3. 搜索高赞图文（开始使用了~~~）

npm.cmd run search -- --keyword "露营装备"

执行成功后，终端会输出结构化 JSON，图片和结果文件会保存在 data 目录。

可选参数：

参数	作用
--keyword / -k	搜索关键词，必填
--no-download	只返回图片 URL，不下载图片
--output D:\xhs-data	指定结果保存根目录

作为 MCP Server 使用

先完成安装、构建和浏览器初始化，然后在 MCP 客户端配置中加入：

{
  "mcpServers": {
    "xhs_searchMcp": {
      "command": "node",
      "args": ["D:xxx\\cyymcp\\dist\\index.js"],
      "cwd": "D:xxx\\cyymcp"
    }
  }
}

请将示例路径替换为你的项目绝对路径，然后重启 MCP 客户端。

调用参数：

{
  "keyword": "露营装备",
  "downloadImages": true,
  "headless": false
}

返回示例：

{
  "success": true,
  "keyword": "露营装备",
  "title": "新手露营装备清单",
  "content": "笔记正文……",
  "author": "作者名称",
  "noteUrl": "https://www.xiaohongshu.com/explore/...",
  "imageUrls": ["https://..."],
  "localImages": ["D:\\xhs-data\\01.jpg"],
  "outputDir": "D:\\xhs-data\\任务目录",
  "retrievedAt": "2026-08-05T01:00:00.000Z"
}

执行失败时，现场截图会保存在：

screenshots/

错误结果包含错误码、错误信息和截图路径，便于在小红书页面结构变化后快速定位问题。

技术栈

• TypeScript
• Node.js
• Playwright
• Model Context Protocol SDK
• Zod