# 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

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

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

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

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

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/                 # 测试套件

# 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

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

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

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

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

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)