小红书评论分析ツール (XHS Comment Analyzer)

ブランドマーケティングチーム向けの小红书UGCコメント自動収集・分析ツール。ブランド語＋カテゴリ語でノートを検索し、コメント（子コメント含む）を一括抽出、キーワード/感情/ホット度の3次元分析を実施し、Excel+JSONの2形式でレポートを出力します。MCP Serverとして動作し、TRAE / Claude / CursorなどのAIクライアントから直接呼び出せるほか、CLIでの単独実行も可能です。

コア機能

• 自動ノート検索：ブランド語＋カテゴリ語の組み合わせで検索、自動スクロール読み込み、無関係なコンテンツをスマートにフィルター

• 一括コメント収集：ノート詳細ページを1つずつ開き、親コメントと子コメントの完全情報を抽出、中断再開に対応

• 3次元分析エンジン：jieba+TF-IDFによるキーワード抽出、感情辞書＋ルールによる感情分類、インタラクション量×時間減衰によるホット度スコアリング

• 2形式レポート出力：5シートのExcelレポート＋構造化JSONデータ

• AIワークフロー統合：MCP Serverが4つのツールを公開、自然言語で全プロセスを駆動可能

Related MCP server: Xiaohongshu (RedBook) MCP Server

クイックスタート

インストール

pip install -e .
playwright install chromium

テスト実行

python -m pytest tests/ -v

CLI使用

# 首次使用：检查登录状态（会打开浏览器，手动完成登录）
python run.py login

# 搜索并抓取评论（使用预设配置）
python run.py search

# 抓取单篇笔记评论
python run.py single "https://www.xiaohongshu.com/search_result/xxx?xsec_token=yyy"

# 对已有 JSON 重新分析
python run.py analyze data/output/report.json

MCP構成

TRAE / Claude / CursorのMCP設定に以下を追加：

{
    "mcpServers": {
        "xhs-comment-analyzer": {
            "command": "python",
            "args": ["-m", "src.mcp_server"],
            "cwd": "/path/to/xhs-comment-analyzer-package"
        }
    }
}

設定後、AIクライアントは自然言語で「小熊電器の小家電のコメントを検索して分析レポートを生成して」と指示できます。

MCPツール一覧

プロジェクト構成

xhs-comment-analyzer-package/
├── src/                                # 源代码
│   ├── scraper/                        # 抓取层
│   │   ├── browser.py                  # Playwright 浏览器管理 (登录态持久化、反检测)
│   │   ├── comment_scraper.py          # 评论抓取核心 (搜索/单篇/批量/断点续抓)
│   │   └── models.py                   # 数据模型 (7 个 Pydantic 模型)
│   ├── analyzer/                       # 分析层
│   │   ├── keywords.py                 # 关键词提取 (jieba + TF-IDF)
│   │   ├── sentiment.py                # 情感分类 (词典 + 规则)
│   │   └── heat.py                     # 热度评分 (互动量 × 时效衰减)
│   ├── exporter/
│   │   └── excel_exporter.py           # 导出 Excel (5 Sheet) + JSON
│   └── mcp_server.py                   # MCP Server (4 个工具)
├── tests/                              # 单元测试 (38 个用例)
├── data/
│   ├── cookies/                        # 登录 cookie 持久化
│   ├── dictionaries/                   # 自定义词典
│   │   ├── domain_words.txt            # 领域词典 (69 个小家电术语)
│   │   ├── stopwords.txt               # 停用词表
│   │   ├── positive_words.txt          # 正面情感词
│   │   ├── negative_words.txt          # 负面情感词
│   │   ├── negation_words.txt          # 否定词
│   │   └── degree_adverbs.txt          # 程度副词 (词<TAB>权重)
│   └── output/                         # 导出文件 (Excel/JSON)
├── docs/                               # 产品文档
│   └── xhs-product-doc.html            # 完整产品文档 (PRD/架构/工作流/算法/接口)
├── run.py                              # CLI 入口 (login/search/single/analyze)
├── conftest.py                         # pytest 配置
├── pyproject.toml                      # 依赖管理
├── .gitignore
└── README.md

出力形式

Excelレポート（5シート）

JSONレポート

構造化された全量データ。task設定、summary統計、keywordsリスト、comments完全リスト、ファイルパスを含み、プログラムによる二次利用が容易です。

コアアルゴリズム

キーワード抽出（jieba + TF-IDF）

各コメントを独立したドキュメントとみなし、jiebaで分詞後、ストップワードと1文字語を除去し、TF-IDF重み（sklearnスタイルの平滑化）を計算。Top10のキーワードとその割合を返します。内蔵の小家電分野辞書（69語）により、複合語が分割されないようにします。

感情分析（辞書＋ルール）

ポジティブ/ネガティブ感情辞書＋否定語反転（前2語ウィンドウ、二重否定対応）＋程度副詞による重み付け（「非常」×1.5、「特別」×2.0など）に基づき、[-1, 1]区間に正規化し、ポジティブ/ネガティブ/ニュートラルのラベルにマッピングします。

ホット度スコア（インタラクション量×時間減衰）

base_score = like_count × 2 + reply_count × 3 + sub_comment_count × 1
time_decay = 0.95 ^ days_ago
heat_score = (base_score × time_decay / max_raw_heat) × 100

返信数の重みが最も高く（3）、深い議論を表します。次いでいいね（2）、子コメントが最も低い（1）。1日あたり5%減衰し、最近の高インタラクションコメントが上位に来るようにします。

セキュリティ設計

• 認証バイパスなし：ツールはアカウント/パスワードの入力、QRコードのシミュレーション、自動CAPTCHA処理を行いません

• 人的介入優先：すべてのログインやCAPTCHA操作は、可視ブラウザウィンドウで人間が完了します

• 可視ブラウザ：常にheadless=Falseを使用し、ユーザーがいつでも表示・介入可能

• リスク警告：連続3回CAPTCHAに遭遇すると自動停止、リスクトリガーを防止

• 中断再開対応：中断後に再開可能、進捗はprogress.jsonに保存

• Cookie永続化：ログイン状態はxhs_cookies.jsonに保存され、頻繁なログインを回避

技術スタック

製品ドキュメント

完全なインタラクティブ製品ドキュメントはdocs/xhs-product-doc.htmlにあり、ブラウザで開くことで閲覧可能です。ドキュメントは9章で構成されています：

1. 製品概要

2. 製品要件ドキュメント（PRD）

3. システムアーキテクチャ

4. ワークフロー

5. コアアルゴリズム

6. セキュリティとアンチディテクション

7. データモデル

8. MCPインターフェース

9. 使用ガイド

サンプルデータ

data/output/ディレクトリには、実際の実行サンプル出力（小熊電器小家電カテゴリ）が含まれており、参考として利用できます：

• ノート数：8件（フィルター後）

• コメント数：58件（子コメント含む）

• 感情分布：ポジティブ22.4%、ネガティブ10.3%、ニュートラル67.2%

• キーワード：小熊、好き、蒸籠

設定と環境変数

• ツールはデフォルトで環境変数やキーを一切必要とせずに動作します。すべてのログイン状態は可視ブラウザ方式で人間が行い、Cookieはdata/cookies/に永続化されます。

• 今後外部サービス（プロキシ、API Keyなど）と連携する場合は、.envファイル（.gitignoreで除外済み）に設定を記述し、.env.exampleテンプレートを参照してください。実際のキーをコミットしないでください。

• 以下のディレクトリ/ファイルは.gitignoreで除外され、バージョン管理されません：data/cookies/*.json（ログイン状態）、data/output/*（収集成果物）、data/progress.json、data/error.log、.envなど。

ディレクトリとファイルの説明

ライセンス

本プロジェクトはMITライセンスのもとでオープンソース化されています。詳細はLICENSEファイル（提供されていない場合は、著者に連絡して入手してください）を参照してください。