reelminner

💡 名称について: このプロジェクトの正式な公開名は Reelminner です。Python エンジンクラスは Reelminner（scraper.py を参照）、CLI/GUIおよびMCPサーバーは reelminner というブランド名、GitHubリポジトリは reelminner です。以前の 開発コードネーム ReelSnipe は完全に廃止されました。その他の名称候補は 名称オプション に記載しています。

📚 目次

• Reelminnerとは

• ✨ 特徴

• 🧠 動作の仕組み

• 🏗️ プロジェクト構成

• 📦 インストール

• 🚀 クイックスタート

• 💻 使い方

  • デスクトップGUI

  • コマンドライン（CLI）

  • MCPサーバー（AIエージェント用）

  • Python API

• 📊 出力形式

• ⚙️ 設定

• 🗂️ プロジェクト構造

• 🧪 テストとQA

• 📦 スタンドアロンEXEのビルド

• ⚠️ 法的・倫理的免責事項

• 🤝 コントリビューション

• 📄 ライセンス

• 🆘 トラブルシューティングとFAQ

• 🏷️ 名称

Related MCP server: Instagram Complete MCP Server

What is Reelminner

Reelminner は、Instagram Reelとその投稿者プロフィールから構造化データを抽出するオープンソースのツールキットです。単一の再利用可能なエンジン（Reelminner）を中心に構築されており、4つの異なる方法で利用できます。

すべてのインターフェースが同じ解析・セッション・レート制限ロジックを共有しているため、どのフロントエンドを使っても結果は同一です。

✨ 特徴

• 多層リール解析 — Reelminnerは複数のレイヤー（埋め込みJSON、GraphQLレスポンス、ライブDOMフォールバック）からデータを読み取るため、Instagramがそのうちの1つを変更しても動作し続けます。

• 投稿者プロフィールの補完 — 各リールについて、投稿者の username、full_name、bio、followers、is_verified、reels_count を自動取得できます。

• フォロワー数抽出 — InstagramのGraphQL UserByRestrictedView / GraphQLOwnerInfo クエリ経由で取得し、DOMフォールバックとページネーションを備えています（「1.2M」のような上限付きフォロワー数表示はプロフィールをスクロールして処理）。

• 楽曲メタデータ — リールの音声 music_title、music_artist、music_id。

• エンゲージメント指標 — views、likes、comments、および直接の video_url / thumbnail。

• セッションとログイン管理 — 対話型QR/ログイン、EditThisCookie エクスポートからのクッキーインポート、24時間のセッション更新により、頻繁な再ログインが不要。

• 並行スクレイピング — スレッドプール（--workers、デフォルト3）と、リクエスト間の適切な遅延（--delay、デフォルト2秒）、さらにInstagramが BLOCKED / RATE_LIMITED を返した際の適応的バックオフを搭載。

• 堅牢なステータス追跡 — 各行に status コード（OK、PARSED_PARTIAL、FAILED、NO_DATA、BLOCKED、RATE_LIMITED）が付与され、何が成功したかを正確に把握できます。

• 複数のエクスポート形式 — CSV（デフォルト）、JSON、Excel（openpyxl による .xlsx）。

• MCPサーバー — AIエージェント（Claude、Cursorなど）がスクレイピング、ステータス確認、クッキーインポート、停止、エクスポートを実行できる5つの安定したツールを提供。

• デスクトップGUI — 内蔵ダークテーマ、URL貼り付けボックス、ライブ結果テーブル、右クリックで URLをコピー / リールを開く、ワンクリックエクスポート。

• テスト済み — pytestスイートと、データ品質ゲートを強制するエンドツーエンドのQAハーネス。

🧠 動作の仕組み

┌────────────┐   ┌────────────┐   ┌────────────┐   ┌────────────┐
│   GUI      │   │    CLI     │   │  MCP srv   │   │  Python    │
│  gui.py    │   │ scraper.py │   │mcp_server  │   │   import   │
└─────┬──────┘   └─────┬──────┘   └─────┬──────┘   └─────┬──────┘
      └────────────────┴────────────────┴────────────────┘
                       ▼
              ┌───────────────────────┐
              │  Reelminner  │  ← the engine (scraper.py)
              │  • session / cookies   │
              │  • thread pool         │
              │  • adaptive back‑off   │
              └───────────┬───────────┘
                          ▼
              ┌───────────────────────┐
              │  parsers.py            │  ← pure extraction helpers
              │  parse_reel_page / json│
              │  parse_owner / music   │
              │  regex adapters         │
              └───────────────────────┘

1. 入力URLの正規化（normalize_reel_url）— /reel/X/ と /reel/s/…/ の両方に対応。

2. セッションの読み込み — 保存済みクッキー（sessionid、csrftoken、ds_user_id、ig_did、mid、rur）を適用するか、ログインします。

3. リールページの取得と解析 — 多層フォールバック方式:

   • parse_reel_page → 埋め込み window.__additionalData / sharedData HTML JSON

   • parse_reel_json → 生のGraphQL GQL レスポンス

   • parse_graphql_reel → shortcodeMedia オブジェクト

   • DOMフォールバック → _extract_text_raw がライブページをクエリし、正規表現アダプターでいいね / コメント / 再生回数 / フォロワー数を取得。

4. 投稿者情報の補完（--no-profiles 指定時を除く）— プロフィールを取得し、followers、full_name、bio、is_verified、reels_count を読み取ります。

5. 制限の尊重 — リクエスト間に delay のスリープを挿入。ブロックされた場合はバックオフして再試行。

6. 書き出し — 各行に status を付けてCSV / JSON / Excelに書き込みます。

🏗️ プロジェクト構成

Reelminnerは単一エンジン・複数インターフェースの設計です。1つのコアエンジン（Reelminner）がすべての実処理を行い、GUI、CLI、MCPサーバー、Python APIはそれを呼び出す薄いフロントエンドです。これにより、解析、セッション処理、レート制限がすべてのエントリポイントで同一になります。

                         ┌─────────────────────────────┐
        URL(s) in ──────▶│     Reelminner     │  scraper.py
                         │  ── engine / orchestrator ──  │
                         └───────┬───────────┬──────────┘
                  run scrapes    │           │  enrich owner
                                 ▼           ▼
                    ┌────────────────┐  ┌──────────────────┐
                    │   parsers.py    │  │ session + graphql│
                    │ pure extractors │  │ (followers/music)│
                    └───────┬────────┘  └─────────┬────────┘
                            └─────────┬────────────┘
                                      ▼
                            ReelData row + status
                                      ▼
                       CSV / JSON / Excel writers

モジュールの役割

エンジン内部（Reelminner）

• セッションレイヤー — _SESSION_COOKIE_NAMES（sessionid、csrftoken、ds_user_id、ig_did、mid、rur）; _apply_cookies()、_refresh_if_needed()（24時間）、login()（対話型QR）、clear_session()。

• 並行処理 — scrape() は ThreadPoolExecutor(max_workers=workers) を起動。各URLは _worker → _scrape_url が処理し、_gather_metadata（リールデータ）とオプションで _gather_article（投稿者プロフィール）を呼び出します。セマフォと _sleep() でポライトネスを確保し、Instagramが BLOCKED / RATE_LIMITED を返した場合は status_code / retcode に基づいて適応的リトライ/バックオフループを実行。

• 解析パイプライン（多層フォールバック） — _gather_metadata 内でエンジンは次の順序で試行: parse_reel_page（埋め込みHTML JSON）→ parse_reel_json（生のGraphQL GQL）→ parse_graphql_reel（shortcodeMedia）→ _extract_text_html / _extract_text_raw アダプターと _PATTERNS 正規表現リスト（いいね/コメント/再生回数/フォロワー数）によるDOMフォールバック。

• プロフィール補完 — get_follower_count() はInstagramのGraphQL UserByRestrictedView / GraphQLOwnerInfo クエリを使用し、DOMフォールバックと、カウントが上限に達した場合のフォロワーページネーション（end_cursor を使用した _fetch_followers）を備えています。

• 出力 — 行は ReelData ディクショナリとして収集され、write_csv（csv_columns を尊重）、export_json、または export_excel（openpyxl が必要）によって書き出されます。

この構成の利点

• テスト容易性 — すべての解析ロジックはブラウザ依存のない parsers.py にあり、tests/test_parsers.py は保存済みのHTML/JSONフィクスチャに対してアサートできます。

• 単一の情報源 — すべてのインターフェースが同じ Reelminner を共有するため、エンジンの修正はGUI、CLI、MCPサーバーに同時に反映されます。

• 安全なパッケージング — GUI/CLIが薄いシェルであるため、PyInstaller EXEはエンジンと最小限のUIのみをバンドルし、バイナリサイズを小さく保てます。

📦 インストール

要件: Python 3.10以上 と Playwright ブラウザエンジン。

# 1. Clone
git clone https://github.com/ilovekushgola/reelminner.git
cd reelminner

# 2. (Recommended) create a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Install the Chromium browser for Playwright
playwright install chromium

GUIのみの場合: デスクトップアプリは標準のPythonインストールに同梱されている tkinter を使用します。 追加パッケージは不要です。GUIはWindowsで最も洗練されています。

オプションの開発/テストツール:

pip install -r requirements-dev.txt   # pytest, coverage

💡 始める前に: Reelminnerはログイン済みのInstagramセッションで最適に動作します — 一部のリールとすべての投稿者/フォロワーデータは認証が必要です。 python scraper.py --login を一度実行するか（対話型QR）、EditThisCookie ブラウザ拡張機能からエクスポートしたクッキーを python scraper.py --import-cookies cookies.json でインポートしてください。 すでに閲覧が許可されている公開コンテンツのみを読み取ります。

🚀 クイックスタート

# Scrape a single reel from the command line
python scraper.py "https://www.instagram.com/reel/CxXYZ123/"

# …or many reels from a file (one URL per line)
python scraper.py -f urls.txt -o export.csv

# Launch the desktop GUI
python gui.py

💻 使い方

1. デスクトップGUI

python gui.py

• ログイン をクリックします（任意ですが推奨 — 成功率が向上します）。

• ボックスに1行につき1つのリールURLを貼り付けます（または Ctrl+A で全選択）。

• Workers スライダーをドラッグし、Scrape をクリックします。

• 結果がテーブルに表示されるのを確認します。

• 行を右クリックすると Copy URL または Open Reel ができます。

• CSV / Excel / JSON にエクスポートするか、結果フォルダを開くことができます。

最後の結果は results/_last_results.json に自動保存されます。

2. コマンドライン（CLI）

python scraper.py [URL ...] [options]

# Headless, 5 workers, 1s delay, no profile enrichment
python scraper.py -f reels.txt -w 5 --delay 1 --headless --no-profiles -o out.csv

3. MCPサーバー（AIエージェント向け）

Reelminner には MCP（Model Context Protocol） サーバーが同梱されており、AIクライアントがこれを操作できます。

python mcp_server.py            # stdio transport

MCPクライアントを設定します（.mcp.json がリポジトリに含まれています）：

{
  "mcpServers": {
    "reelminner": {
      "command": "python",
      "args": ["mcp_server.py"],
      "cwd": ".",
      "env": { "RMIN_HEADLESS": "true" }
    }
  }
}

公開ツール（5つ、安定版）：

環境変数の上書き： RMIN_HEADLESS、RMIN_WORKERS、RMIN_DELAY、RMIN_WITH_PROFILES。

4. Python API

from scraper import Reelminner, write_csv

scraper = Reelminner(workers=3, delay=2.0, headless=True)
rows, report = scraper.scrape(
    ["https://www.instagram.com/reel/CxXYZ123/"],
    with_profiles=True,
)
write_csv(rows, "out.csv")

for r in rows:
    print(r["username"], r["followers"], r["likes"], r["status"])

Reelminner の主要メンバー：

• scrape(urls, with_profiles=True) → (rows, report)

• login() — 対話的ログイン

• has_session() / save_cookies_from_file(path) / clear_session()

• write_csv(rows, path)、export_json(rows, path)、export_excel(rows, path)

• normalize_reel_url(url) — 公開ヘルパー

• csv_columns — 出力フィールドの順序付きリスト

• DEFAULT_STATE_FILE — デフォルトの storage_state.json

📊 出力形式

各リールが1行になります。完全なCSVスキーマ（scraper.csv_columns）：

⚙️ 設定

クッキー / セッション

• python scraper.py --login でログインします（storage_state.json が保存されます）。

• または、ブラウザの EditThisCookie 拡張機能からクッキーをエクスポートし、 python scraper.py --import-cookies cookies.json を実行します。

環境変数（MCPサーバーとCLIのデフォルトで使用）

テンプレートが用意されています：mcp.env.example を mcp.env にコピーしてMCPのデフォルトを上書きします。

🗂️ プロジェクト構成

reelminner/
├── scraper.py          # Core engine: Reelminner + CLI
├── gui.py              # Tkinter desktop application
├── parsers.py          # Pure extraction helpers (HTML/JSON/music/regex)
├── mcp_server.py       # MCP server (5 tools for AI agents)
├── theme.py            # Dark‑theme styling for the GUI
├── build_exe.py        # PyInstaller build script
├── Reelminner.spec  # PyInstaller spec (one‑file EXE)
├── run_qa.py           # End‑to‑end QA harness with data‑quality gates
├── requirements.txt    # Runtime dependencies
├── requirements-dev.txt# Dev / test dependencies
├── mcp.env.example     # MCP env template
├── .mcp.json           # MCP client configuration
├── assets/             # Icons (icon.ico)
├── docs/               # SKILL.md, E2E test/fix plan
├── skills/             # Agent skill definition
├── tests/              # pytest suite + corpus.txt
└── results/            # Scrape outputs (git‑ignored)

🧪 テストとQA

# Unit / integration tests
pytest -q

# End‑to‑end data‑quality run (uses your saved session)
python run_qa.py                 # full run over tests/corpus.txt
python run_qa.py --quick         # 1 URL, headless, fast iteration
python run_qa.py --url <reel>    # custom single URL
python run_qa.py --report-only   # show last qa_report.json

QAハーネスは、解析率、認証率、非空率、ブロック率、最大実行時間などのゲートを強制し、results/qa/qa_report.json と qa_results.csv を書き出します。

📦 スタンドアロンEXEのビルド

Windowsでは、ポータブルな .exe を生成できます（エンドユーザーにPythonは不要）：

pip install pyinstaller
python build_exe.py

出力：dist/Reelminner.exe（Reelminner.spec によるワンファイルビルド）。

⚠️ 法的・倫理的免責事項

Reelminner は教育目的および許可された/個人利用のみを目的として提供されています。

• Instagramのスクレイピングは、その利用規約に違反する可能性があります。所有している、またはアクセスを許可されているコンテンツにのみ使用してください。

• レート制限を尊重し（--delay、少ない --workers）、スパム、嫌がらせ、商業的な大量抽出には使用しないでください。

• このツールの使用方法と、お住まいの地域の適用法令（GDPR / プライバシー規制を含む）への準拠については、利用者自身が責任を負います。

• 作者は Instagram/Meta とは提携しておらず、いかなる責任も負いません。

🆘 トラブルシューティングとFAQ

playwright がブラウザがインストールされていない / ページが開かないと表示する → pip install -r requirements.txt と playwright install chromium の両方を実行したことを確認してください。Chromiumのダウンロードがないと何も起動しません。

ほとんどのフィールドが空、または BLOCKED / RATE_LIMITED が返る → ログイン（python scraper.py --login）するかクッキーをインポートし、速度を落としてください：--delay 4 と少ないワーカー数（-w 1）。Instagramは匿名/未認証のトラフィックを最も厳しく制限するため、認証済みセッションが最大の成功要因です。

リールが NO_DATA を返す → 投稿が非公開、削除済み、地域制限されているか、Instagramがログイン壁を表示している可能性があります。ログイン済みセッションでもう一度試してください。

GUIウィンドウが開かない、またはフォントが正しく表示されない → GUIはPython組み込みの tkinter を使用しています。Windowsで最も洗練されています。Linux/macOSでは、ウィンドウが起動しない場合にTkパッケージをインストールしてください（例：sudo apt install python3-tk）。

スクリプト実行時に ModuleNotFoundError が発生する → リポジトリまたはその仮想環境の外にいる可能性があります。プロジェクトフォルダに cd し、python scraper.py を実行する前にvenvをアクティベートしてください（Windowsでは .venv\Scripts\activate、macOS/Linuxでは source .venv/bin/activate）。

一度に大量のリールをスクレイプするには？ → テキストファイルに1行につき1つのURLを入れ、 python scraper.py -f urls.txt -o out.csv を実行します。

AIエージェントで使用できますか？ → はい — python mcp_server.py を実行し、任意のMCPクライアント（Claude Desktop、Cursorなど）を同梱の .mcp.json にポイントします。MCPサーバー を参照してください。

🤝 コントリビューション

1. リポジトリをフォークし、機能ブランチを作成します。

2. pip install -r requirements-dev.txt

3. tests/ にテストを追加/調整し、pytest と python run_qa.py --quick を実行します。

4. 変更内容とQA結果を説明するプルリクエストを開きます。

📄 ライセンス

MITライセンス の下で公開されています — LICENSE を参照してください。

🏷️ 名称

プロジェクトの最終的な公開名は Reelminner（「リールマイナー」）です。以前の内部コードネームは廃止されました。フォークする場合は、好きな名前に変更できます — gui.py とこのREADMEのタイトルを更新するだけです。