rednote-crawler

rednote-crawler

中文 | English

---

中文

小红书 (Xiaohongshu / REDnote) 数据采集框架 + MCP 服务。

基于 Playwright 实现真实浏览器自动化，具备双层反检测能力（playwright-stealth + browserforge）。通过 MCP 协议将采集能力暴露为标准工具，让 AI 助手（Claude Desktop / Code / Cursor）直接调用。

功能特性

• MCP 服务：AI 助手可直接搜索小红书、采集笔记详情和评论
• 多种 Transport：stdio（本地）/ SSE（远程部署）/ Streamable HTTP
• 关键词搜索采集（瀑布流自动滚动加载）
• 笔记详情采集（标题、正文、互动数据、标签、图片/视频）
• 评论采集（Top N 评论，含用户信息和 IP 属地）
• 双层反检测（playwright-stealth 环境级 + browserforge 指纹级）
• 登录状态持久化（扫码登录后自动保存，下次启动免登录）
• 数据输出：JSON（原始完整）+ Excel/xlsx（3 个 Sheet 结构化）
• 生产级稳定性：超时控制、浏览器崩溃自动恢复、登录态失效检测

环境要求

• Python 3.10+
• uv 包管理器

快速开始

# 1. 克隆仓库
git clone https://github.com/yangsijie666/xiaohongshu-crawler.git && cd xiaohongshu-crawler

# 2. 安装依赖
uv sync

# 3. 安装浏览器
uv run playwright install chromium

# 4. 首次登录（扫码）
uv run python scripts/verify_login.py

# 5. 运行采集
uv run python main.py

MCP 服务使用

方式一：stdio 模式（推荐，本地集成）

在 Claude Desktop 配置文件中添加（Mac: ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "rednote-crawler": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/rednote-crawler", "python", "mcp_server.py"],
      "env": {}
    }
  }
}

方式二：SSE 模式（远程部署）

# 服务器端启动
uv run python mcp_server.py --transport sse --host 0.0.0.0 --port 8000

客户端配置：

{
  "mcpServers": {
    "rednote-crawler": {
      "url": "http://your-server:8000/sse"
    }
  }
}

方式三：Streamable HTTP 模式

uv run python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 8000

MCP 工具列表

| 工具 | 说明 | 耗时 | |------|------|------| | check_login_status | 检查登录状态 | 5-10s | | search_notes | 关键词搜索笔记（max_count 1-50） | 30-90s | | get_note_detail | 采集笔记详情 + 评论 | 15-60s | | crawl_keyword | 完整流程：搜索→详情→评论→存储 | 2-15min | | get_saved_data | 查询本地已保存数据 | <1s |

命令参考

| 命令 | 说明 | |------|------| | uv sync | 安装/同步项目依赖 | | uv run playwright install chromium | 安装 Chromium 浏览器 | | uv run python main.py | 运行完整采集流程 | | uv run python mcp_server.py | 启动 MCP 服务（stdio） | | uv run python mcp_server.py --transport sse | 启动 MCP 服务（SSE） | | uv run python scripts/verify_login.py | 验证/完成登录 | | uv run python scripts/verify_stealth.py | 验证反检测效果 | | uv run python scripts/verify_search.py | 验证搜索采集 | | uv run python scripts/verify_note.py | 验证笔记详情+评论采集 | | uv run pytest --cov | 运行测试 + 覆盖率 |

配置说明

编辑 config/settings.yaml：

| 配置项 | 默认值 | 说明 | |--------|--------|------| | crawler.keywords | ["示例关键词"] | 搜索关键词列表 | | crawler.max_notes_per_keyword | 20 | 每个关键词最多采集笔记数 | | crawler.max_comments_per_note | 20 | 每条笔记最多采集评论数 | | crawler.scroll_pause | 1.5 | 滚动后等待时间（秒） | | crawler.page_load_timeout | 30 | 页面加载超时（秒） | | delay.between_notes | [2, 5] | 笔记之间随机延迟范围（秒） | | delay.between_searches | [3, 8] | 搜索之间随机延迟范围（秒） | | browser.headless | false | 是否无头模式 | | storage.output_dir | "data" | 输出目录 | | storage.save_raw_json | true | 是否保存原始 JSON | | storage.save_xlsx | true | 是否保存 Excel |

输出格式

data/
├── raw/
│   ├── {keyword}_{timestamp}.json          # 搜索结果
│   └── notes_{keyword}_{timestamp}.json    # 笔记详情+评论
└── processed/
    └── {keyword}_{timestamp}.xlsx          # Excel 工作簿
        ├── Sheet 1: 搜索结果 (8 列)
        ├── Sheet 2: 笔记详情 (13 列)
        └── Sheet 3: 评论数据 (8 列)

项目结构

mcp_server.py          # MCP 服务入口（支持 stdio / SSE / HTTP）
main.py                # CLI 采集入口
src/
├── session.py         # MCP 会话管理（浏览器生命周期 + 并发锁）
├── errors.py          # 统一错误格式
├── stealth.py         # 反检测配置（指纹生成 + stealth 注入）
├── browser.py         # Playwright 浏览器生命周期管理
├── auth.py            # 登录 & 会话管理
├── search.py          # 搜索结果采集（瀑布流滚动）
├── note.py            # 笔记详情采集（含重试逻辑）
├── comment.py         # 评论采集（Top N）
├── parser.py          # 页面数据解析
└── storage.py         # 数据存储（JSON + Excel/xlsx）
scripts/               # 验证脚本
config/                # YAML 配置
tests/                 # 测试套件

依赖

| 包 | 用途 | |----|------| | playwright | 浏览器自动化 (async API) | | playwright-stealth | 反检测补丁 | | browserforge | 真实浏览器指纹生成 | | mcp[cli] | MCP 协议 SDK | | uvicorn | ASGI 服务器（SSE/HTTP transport） | | starlette | ASGI 框架（SSE/HTTP transport） | | pyyaml | YAML 配置加载 | | openpyxl | Excel 工作簿生成 |

许可证

MIT

---

English

Xiaohongshu (REDnote) data collection framework + MCP server.

Built on Playwright for real browser automation with dual-layer anti-detection (playwright-stealth + browserforge). Exposes collection capabilities as standard MCP tools for AI assistants (Claude Desktop / Code / Cursor).

Features

• MCP Server: AI assistants can directly search REDnote, collect note details and comments
• Multiple Transports: stdio (local) / SSE (remote) / Streamable HTTP
• Keyword search with infinite scroll auto-loading
• Note detail collection (title, content, engagement metrics, tags, images/videos)
• Comment collection (Top N comments with user info and IP location)
• Dual-layer anti-detection (environment-level + fingerprint-level)
• Persistent login state (auto-saved after QR code scan)
• Output: JSON (raw) + Excel/xlsx (3-sheet structured)
• Production-grade reliability: timeout control, browser crash auto-recovery, login expiry detection

Requirements

• Python 3.10+
• uv package manager

Quick Start

# 1. Clone
git clone <repo-url> && cd rednote-crawler

# 2. Install dependencies
uv sync

# 3. Install browser
uv run playwright install chromium

# 4. First login (QR code scan)
uv run python scripts/verify_login.py

# 5. Run collection
uv run python main.py

MCP Server Usage

Option A: stdio Mode (Recommended, Local Integration)

Add to Claude Desktop config (Mac: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rednote-crawler": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/rednote-crawler", "python", "mcp_server.py"],
      "env": {}
    }
  }
}

Option B: SSE Mode (Remote Deployment)

# Start on server
uv run python mcp_server.py --transport sse --host 0.0.0.0 --port 8000

Client config:

{
  "mcpServers": {
    "rednote-crawler": {
      "url": "http://your-server:8000/sse"
    }
  }
}

Option C: Streamable HTTP Mode

uv run python mcp_server.py --transport streamable-http --host 0.0.0.0 --port 8000

MCP Tools

| Tool | Description | Latency | |------|-------------|---------| | check_login_status | Check login status | 5-10s | | search_notes | Search notes by keyword (max_count 1-50) | 30-90s | | get_note_detail | Collect note details + comments | 15-60s | | crawl_keyword | Full pipeline: search → details → comments → save | 2-15min | | get_saved_data | Query locally saved data files | <1s |

CLI Reference

| Command | Description | |---------|-------------| | uv run python mcp_server.py | Start MCP server (stdio) | | uv run python mcp_server.py --transport sse | Start MCP server (SSE) | | uv run python mcp_server.py --transport sse --host 0.0.0.0 --port 9090 | SSE with custom host/port | | uv run python main.py | Run full collection pipeline | | uv run python scripts/verify_login.py | Login via QR code | | uv run pytest --cov | Run tests with coverage |

Project Structure

mcp_server.py          # MCP server entry (stdio / SSE / HTTP)
main.py                # CLI collection entry
src/
├── session.py         # MCP session (browser lifecycle + concurrency lock)
├── errors.py          # Unified error format
├── stealth.py         # Anti-detection (fingerprint + stealth injection)
├── browser.py         # Playwright browser lifecycle
├── auth.py            # Login & session management
├── search.py          # Search collection (infinite scroll)
├── note.py            # Note detail collection (with retry)
├── comment.py         # Comment collection (Top N)
├── parser.py          # Page data parsing
└── storage.py         # Data storage (JSON + Excel/xlsx)

License

MIT