Media Crawler MCP Service

🚀 MediaCrawler MCP サービス

AI がソーシャルメディアデータを直接利用できるようにする MCP サービスです。従来の CLI クローラーを MCP 標準ツールにアップグレードし、Claude / ChatGPT から直接呼び出せるようにします。一度設定すれば、長期間利用可能です。

🚀 クイックスタート

環境要求：Python 3.8+ · Redis · Chrome/Chromium ·（オプション）Node.js 16+

1. リポジトリをクローンし、依存関係をインストールします。

git clone <your-repo-url>
cd media-crawler-mcp-service
poetry install
poetry run playwright install chromium

2. 環境を設定します。

cp .env.example .env
# 必要に応じてポート/プラットフォームスイッチ/Redis などを変更します。

3. サービスを起動します。

redis-server                 # 未起動の場合
poetry run python main.py    # デフォルトポート 9090

# 管理画面: http://localhost:9090/admin
# ツールデバッグ: http://localhost:9090/admin/inspector

✨ 主な機能

• 一度設定すれば、AI（Claude/ChatGPT）から直接呼び出せます。
• ログイン管理を外部化し、再起動後も状態を保持し、複数プラットフォームをサポートします。
• タスクレベルでの設定分離により、グローバル変数の競合を解消します。
• Playwright のブラウザコンテキストを再利用し、秒単位で応答します。
• Pydantic を使用した構造化出力で、分析とアーカイブが容易です。
• 内蔵の状態キャッシュとリスク管理に配慮した戦略を備えています。

現在実装済みと進行中の機能：

• 実装済み：B 站の検索/詳細/クリエイター/コメント（bili_search/bili_detail/bili_creator/bili_comments）
• 進行中：小红书 / 抖音 / 快手 / 知乎 / 贴吧 / 微博 など

📚 ドキュメント

プロジェクト概要

MediaCrawler MCP Service は「学習と研究」を目的としたデータ取得ツールセットです。MCP（Model Context Protocol）を通じて、ソーシャルメディアの公開情報を AI アシスタントが直接呼び出せる標準化されたツールに変換します。主な機能には「外部化されたログイン管理」「タスクレベルでの設定分離」「ブラウザコンテキストの再利用」「構造化データの出力」が含まれます。

なぜこのサービスが他と異なるのか？

• スクリプトから標準ツールへ：使い捨てのスクリプトから再利用可能な MCP ツールへの進化。
• 完全な外部化ログイン：可視化インターフェース + 二次元コード/Cookie の二重モードで、状態を永続化。
• 本格的なエンジニアリング：階層化された解耦、Pydantic モデル、状態キャッシュとリスク管理に配慮した設計。
• テキスト形式に適した出力：AI 分析に適したテキスト形式で出力し、大量の無駄なネストデータを避けます。

管理画面とログイン

1. 管理画面 http://localhost:9090/admin を開きます。
2. 「ログイン管理」に入り、プラットフォーム（例：B 站）を選択します。
3. 「二次元コードログイン」または「Cookie ログイン」をサポートし、状態は永続化されます。

AI アシスタントでの使用方法

Claude/ChatGPT で直接 MCP ツールを呼び出すことができます。

サンプル会話：
「Python 機械学習に関する B 站の動画を検索し、人気度とクリエイターを分析してください。」
→ 自動的に `bili_search` を呼び出してデータを取得 → 指標を組み合わせて分析 → 洞察を出力

ツールの概要

管理ページの MCP Tools Inspector で、登録されているすべてのツールを確認し、オンラインでデバッグすることができます。

• bili_search（おすすめ、高速検索）

{
  "keywords": "Python 機械学習",
  "page_size": 3,
  "page_num": 1
}

• bili_detail（指定動画の詳細）

{ "video_ids": ["115285696846946"] }

• bili_creator（クリエイター分析）

{ "creator_ids": ["99801185"], "creator_mode": true }

アーキテクチャと技術選択

🤖 AI アシスタント (Claude / ChatGPT)
           │  MCP Protocol
           ▼
🎯 MediaCrawler MCP Service
  ├─ 管理層: ログイン/状態/設定
  ├─ サービス層: 各プラットフォームの編成 (Bili…)
  └─ ツール層: bili_search/detail/creator/comments
           │
           ▼
🌐 Playwright Browser（コンテキストの再利用 / リスク管理に配慮）
           │
           ▼
💾 Redis 状態キャッシュ · ローカル/構造化ストレージ

従来の CLI スクリプトとの比較：

• 呼び出し方法：スクリプト → MCP ツール（AI 対応）
• ログイン管理：スクリプト内のロジック → 外部化されたページ + 永続化
• パフォーマンス：毎回のコールドスタート → ブラウザの常駐と再利用
• 設計：グローバル変数 → タスクレベルでの設定分離
• 出力：生データ → Pydantic 構造化データ

Roadmap

• 小红书 / 抖音 / 快手 / 知乎 / 微博 / 贴吧 への対応
• ツールデバッガーと可視化機能の強化（フィルタリング、エクスポート、トレンド分析）
• より細かいレート制御とリスク管理戦略
• より多くのストレージターゲット（SQLite/DB の永続化）

開発と貢献

参考パス：

• 起動エントリー：main.py:1
• アプリケーションファクトリ：app/api_service.py:1
• 管理画面ルート：app/api/endpoints/admin/admin_page_endpoint.py:1
• ツールリストインターフェース：app/api/endpoints/admin/mcp_inspector_endpoint.py:1

新しいプラットフォームを追加する典型的な手順：

1. ログインアダプターを追加：app/core/login/{platform}/...
2. プラットフォームのクローラーと編成を実装：app/core/crawler/platforms/{platform}/...
3. MCP ツールとしてラップ：app/core/mcp_tools/{platform}.py
4. ルートを登録：app/api/endpoints/mcp/{platform}.py

より多くのデプロイと運用オプション：deploy/README.md:1

貢献の流れ：

1. Fork して特性ブランチを作成します。
2. プロジェクト規約を読む：Agent.md:1
3. ローカルで開発して自己テストを行います。
4. PR を提出し、変更点を説明します。

FAQ

起動に失敗した場合：

poetry install
poetry run playwright install chromium
redis-cli ping   # 期待値: PONG
APP__DEBUG=true poetry run python main.py

二次元コードが表示されない場合：

BROWSER__HEADLESS=false poetry run python main.py
poetry run playwright install-deps chromium

ログイン状態が失われやすい場合：

• Redis が安定していること、ネットワークが正常であることを確認し、高頻度でのリスク管理トリガーを避けます。

検索結果が空または遅い場合：

• まず bili_search を使用し、ページサイズを小さくし、リクエスト間隔を長くします。

コンプライアンスと適切な使用

このプロジェクトは「学習と研究」を目的とした効率的なツールです。

• 各プラットフォームの利用規約と robots.txt を遵守します。
• 適切な頻度でリクエストを行い、プラットフォームに負担をかけないようにします。
• コンテンツクリエイターを尊重し、商業目的でのクローリングには使用しないでください。
• 一度のリクエスト量を少なくし、リクエスト間隔を 2 秒以上に設定することをおすすめします。

このプロジェクトがあなたの学習に役立った場合は、⭐ Star でサポートしていただけると幸いです！