小红书爬虫 MCP 工具 (XHS Spider MCP)

一个基于 Model Context Protocol (MCP) 的小红书数据爬取工具，支持笔记信息获取、用户作品爬取、关键词搜索等功能。

✨ 功能特性

• 🔍 笔记信息获取：获取小红书笔记的详细信息，包括作者、内容、互动数据、媒体文件等
• 👤 用户作品爬取：获取指定用户发布的所有笔记链接列表
• 🔎 关键词搜索：根据关键词搜索小红书笔记，支持多种排序和筛选选项
• ⚡ 高性能异步：基于 TypeScript 和 axios 构建，支持并发请求和重试机制
• 🛡️ 错误处理：完善的错误处理和重试机制，提供详细的错误信息
• 📊 标准化输出：统一的 JSON 格式响应，便于数据处理和分析

📦 安装

使用 npm

npm install -g xhs-spider-mcp

从源码构建

git clone https://github.com/your-username/xhs-spider-mcp.git
cd xhs-spider-mcp
npm install
npm run build

⚙️ 配置

环境变量设置

你需要设置小红书的 Cookies 才能使用此工具：

1. 设置环境变量：

   export XHS_COOKIES="your_xiaohongshu_cookies_here"

2. 创建 .env 文件：

   echo "XHS_COOKIES=your_xiaohongshu_cookies_here" > .env

3. 在用户目录创建配置：

   mkdir -p ~/.xhs-spider-mcp
   echo "XHS_COOKIES=your_xiaohongshu_cookies_here" > ~/.xhs-spider-mcp/.env

获取 Cookies

1. 打开浏览器，登录小红书网站 (https://www.xiaohongshu.com)
2. 打开开发者工具 (F12)
3. 切换到 Network 标签页
4. 刷新页面或进行任何操作
5. 找到任意一个请求，在请求头中找到 Cookie 字段
6. 复制整个 Cookie 字符串

注意：Cookie 包含敏感信息，请妥善保管，不要泄露给他人。

🚀 使用方法

作为 MCP 服务器

# 启动 MCP 服务器
xhs-spider-mcp

# 或者在开发模式下运行
npm run dev

MCP 工具列表

1. get-note

获取小红书笔记的详细信息

参数：

• note_url (string): 小红书笔记链接

示例：

{
  "note_url": "https://www.xiaohongshu.com/explore/683fe17f0000000023017c6a?xsec_token=ABBr_cMzallQeLyKSRdPk9fwzA0torkbT_ubuQP1ayvKA=&xsec_source=pc_user"
}

2. get-user-notes

获取指定用户发布的所有笔记链接列表

参数：

• user_url (string): 小红书用户主页链接

示例：

{
  "user_url": "https://www.xiaohongshu.com/user/profile/64c3f392000000002b009e45?xsec_token=AB-GhAToFu07JwNk_AMICHnp7bSTjVz2beVIDBwSyPwvM=&xsec_source=pc_feed"
}

3. search-notes

根据关键词搜索小红书笔记

参数：

• query (string): 搜索关键词
• count (number, 可选): 返回结果数量，默认20，最大100
• sort_type (number, 可选): 排序方式
  • 0: 综合排序 (默认)
  • 1: 最新
  • 2: 最多点赞
  • 3: 最多评论
  • 4: 最多收藏
• note_type (number, 可选): 笔记类型
  • 0: 不限 (默认)
  • 1: 视频笔记
  • 2: 普通笔记
• time_filter (number, 可选): 时间筛选
  • 0: 不限 (默认)
  • 1: 一天内
  • 2: 一周内
  • 3: 半年内

示例：

{
  "query": "美食",
  "count": 10,
  "sort_type": 1,
  "note_type": 0,
  "time_filter": 0
}

作为 TypeScript 库使用

import { XHSClient, XHSDataUtil } from 'xhs-spider-mcp';

// 创建客户端实例
const client = new XHSClient({
  cookies: 'your_cookies_here',
  debug: true
});

// 获取笔记信息
const noteResult = await client.getNoteInfo('https://www.xiaohongshu.com/explore/...');
if (noteResult.success) {
  console.log('笔记信息：', noteResult.data);
}

// 获取用户所有笔记
const userNotesResult = await client.getUserAllNotes('https://www.xiaohongshu.com/user/profile/...');
if (userNotesResult.success) {
  console.log('用户笔记数量：', userNotesResult.data.length);
}

// 搜索笔记
const searchResult = await client.searchNotes('美食', 20, 0, 0, 0);
if (searchResult.success) {
  console.log('搜索结果：', searchResult.data);
}

📊 响应格式

所有工具都返回标准化的 JSON 格式：

成功响应

{
  "status": "success",
  "message": "操作成功",
  "data": {
    // 具体的数据内容
  },
  "timestamp": "2024-01-01T00:00:00.000Z"
}

错误响应

{
  "status": "error", 
  "message": "错误描述",
  "error": "详细错误信息",
  "timestamp": "2024-01-01T00:00:00.000Z"
}

笔记信息格式

{
  "id": "笔记ID",
  "title": "笔记标题",
  "desc": "笔记描述",
  "type": "笔记类型 (normal/video)",
  "user": {
    "id": "用户ID",
    "nickname": "用户昵称",
    "avatar": "用户头像URL"
  },
  "interact_info": {
    "liked_count": "点赞数",
    "collected_count": "收藏数",
    "comment_count": "评论数",
    "share_count": "分享数"
  },
  "image_list": [
    {
      "url": "图片URL",
      "width": "图片宽度",
      "height": "图片高度"
    }
  ],
  "video": {
    "url": "视频URL",
    "width": "视频宽度", 
    "height": "视频高度",
    "duration": "视频时长"
  },
  "tag_list": [
    {
      "id": "标签ID",
      "name": "标签名称",
      "type": "标签类型"
    }
  ],
  "url": "笔记链接",
  "time": "发布时间戳"
}

🔧 开发

环境要求

• Node.js >= 14.0.0
• TypeScript >= 5.1.3

开发命令

# 安装依赖
npm install

# 开发模式运行
npm run dev

# 构建项目
npm run build

# 启动服务
npm start

# 运行测试
npm test

项目结构

xhs-spider-mcp/
├── src/                    # 源代码
│   ├── index.ts           # 主要客户端类
│   └── dotenv-silent.ts   # 环境变量处理
├── examples/              # 示例代码
│   └── mcp-server.ts      # MCP 服务器实现
├── dist/                  # 编译输出
├── mcp.json              # MCP 配置文件
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript 配置
└── README.md             # 项目文档

⚠️ 注意事项

1. 合规使用：本工具仅供学习和研究使用，请遵守小红书的使用条款和robots.txt规则
2. 频率限制：为避免被限制，建议在请求之间添加适当的延迟
3. Cookie 有效期：Cookies 有有效期限制，失效后需要重新获取
4. 数据准确性：由于网站结构可能变化，数据解析可能需要更新
5. 隐私保护：请保护好用户隐私，不要滥用获取的数据

🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

📄 许可证

本项目采用 MIT License 许可证。

🙏 致谢

• Model Context Protocol - MCP 协议规范
• 小红书 - 数据来源

📞 支持

如有问题或建议，请通过以下方式联系：

• 创建 GitHub Issue
• 邮箱：[email protected]

声明：本工具仅供学习研究使用，请遵守相关法律法规和网站服务条款。