# xhs_searchMcp

> **还在手动打开小红书、输入关键词、点开筛选、寻找高赞笔记，再一张张保存图片、复制标题和正文？**
>
> 把关键词交给 `xhs_searchMcp` 就够了。它会自动完成搜索与筛选，找到“图文 · 最多点赞”的第一篇笔记，并将标题、正文、作者、链接和图片整理成可以直接交给 AI 或程序使用的结构化数据。

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

## 它能做什么？

只需传入一个关键词：

```text
露营装备
```

`xhs_searchMcp` 会自动执行：

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

主要特性：

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

## 环境要求

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

## 快速开始

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

```bash
npm install
npx playwright install chromium
```

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

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

```powershell
npm run build
npm.cmd run setup-profile
```

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

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

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

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

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

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

可选参数：

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

## 作为 MCP Server 使用

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

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

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

调用参数：

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

返回示例：

```json
{
  "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"
}
```

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

```text
screenshots/
```

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

## 技术栈

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