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

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Node](https://img.shields.io/badge/node-%3E%3D14.0.0-green.svg)
![TypeScript](https://img.shields.io/badge/typescript-5.1.3-blue.svg)

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

## ✨ 功能特性

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

## 📦 安装

### 使用 npm

```bash
npm install -g xhs-spider-mcp
```

### 从源码构建

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

## ⚙️ 配置

### 环境变量设置

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

1. **设置环境变量**：
   ```bash
   export XHS_COOKIES="your_xiaohongshu_cookies_here"
   ```

2. **创建 .env 文件**：
   ```bash
   echo "XHS_COOKIES=your_xiaohongshu_cookies_here" > .env
   ```

3. **在用户目录创建配置**：
   ```bash
   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 服务器

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

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

### MCP 工具列表

#### 1. get-note
获取小红书笔记的详细信息

**参数：**
- `note_url` (string): 小红书笔记链接

**示例：**
```json
{
  "note_url": "https://www.xiaohongshu.com/explore/683fe17f0000000023017c6a?xsec_token=ABBr_cMzallQeLyKSRdPk9fwzA0torkbT_ubuQP1ayvKA=&xsec_source=pc_user"
}
```

#### 2. get-user-notes
获取指定用户发布的所有笔记链接列表

**参数：**
- `user_url` (string): 小红书用户主页链接

**示例：**
```json
{
  "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: 半年内

**示例：**
```json
{
  "query": "美食",
  "count": 10,
  "sort_type": 1,
  "note_type": 0,
  "time_filter": 0
}
```

### 作为 TypeScript 库使用

```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 格式：

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

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

### 笔记信息格式
```json
{
  "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

### 开发命令
```bash
# 安装依赖
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](LICENSE) 许可证。

## 🙏 致谢

- [Model Context Protocol](https://github.com/modelcontextprotocol/specification) - MCP 协议规范
- [小红书](https://www.xiaohongshu.com) - 数据来源

## 📞 支持

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

- 创建 [GitHub Issue](https://github.com/your-username/xhs-spider-mcp/issues)
- 邮箱：your-email@example.com

---

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