Crawl-MCP: crawl4ai用非公式MCPサーバー

⚠️ 重要: これは優れた crawl4ai ライブラリのための非公式MCPサーバー実装です。 元のcrawl4aiプロジェクトとは提携していません。

強力なcrawl4aiライブラリを高度なAI機能でラップした、包括的なModel Context Protocol (MCP) サーバーです。Webページ、PDF、Officeドキュメント、YouTube動画など、あらゆるソースからコンテンツを抽出・分析します。インテリジェントな要約機能を備えており、重要な情報を保持しながらトークン消費量を劇的に削減します。

🌟 主な機能

• 🔍 Google検索統合 - Google公式演算子を使用した7つの最適化された検索ジャンル

• 🔍 高度なWebクローリング: JavaScriptサポート、詳細なサイトマッピング、エンティティ抽出

• 🌐 ユニバーサルコンテンツ抽出: Webページ、PDF、Wordドキュメント、Excel、PowerPoint、ZIPアーカイブ

• 🤖 AIによる要約: 重要な情報を保持しつつ、スマートなトークン削減（最大88.5%）

• 🎬 YouTube統合: APIキーなしで動画の文字起こしと要約を抽出

• ⚡ 本番環境対応: 包括的なエラーハンドリングを備えた19の専門ツール

Related MCP server: Crawl4AI MCP Server

🚀 クイックスタート

前提条件（最初に必須）

• Python 3.11 以上（FastMCP が Python 3.11+ を要求）

Playwright用のシステム依存関係のインストール:

Ubuntu 24.04 LTS (手動実行が必要):

# Manual setup required due to t64 library transition
sudo apt update && sudo apt install -y \
  libnss3 libatk-bridge2.0-0 libxss1 libasound2t64 \
  libgbm1 libgtk-3-0t64 libxshmfence-dev libxrandr2 \
  libxcomposite1 libxcursor1 libxdamage1 libxi6 \
  fonts-noto-color-emoji fonts-unifont python3-venv python3-pip

python3 -m venv venv && source venv/bin/activate
pip install playwright==1.55.0 && playwright install chromium
sudo playwright install-deps

その他のLinux/macOS:

sudo bash scripts/prepare_for_uvx_playwright.sh

Windows (管理者として実行):

scripts/prepare_for_uvx_playwright.ps1

インストール

UVX (推奨 - 最も簡単):

# After system preparation above - that's it!
uvx --from git+https://github.com/walksoda/crawl-mcp crawl-mcp

Docker (本番環境対応):

# Clone the repository
git clone https://github.com/walksoda/crawl-mcp
cd crawl-mcp

# Build and run with Docker Compose (STDIO mode)
docker-compose up --build

# Or build and run HTTP mode on port 8000
docker-compose --profile http up --build crawl4ai-mcp-http

# Or build manually
docker build -t crawl4ai-mcp .
docker run -it crawl4ai-mcp

Dockerの機能:

• 🔧 マルチブラウザサポート: Chromium、Firefox、Webkitヘッドレスブラウザ

• 🐧 Google Chrome: 互換性のための追加のChrome Stable

• ⚡ 最適化されたパフォーマンス: Docker用に事前設定されたブラウザフラグ

• 🔒 セキュリティ: 非rootユーザー実行

• 📦 完全な依存関係: 必要なすべてのライブラリが含まれています

Claude Desktopの設定

UVXインストール: claude_desktop_config.json に以下を追加します:

{
  "mcpServers": {
    "crawl-mcp": {
      "transport": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/walksoda/crawl-mcp",
        "crawl-mcp"
      ],
      "env": {
        "CRAWL4AI_LANG": "en"
      }
    }
  }
}

Docker HTTPモード:

{
  "mcpServers": {
    "crawl-mcp": {
      "transport": "http",
      "baseUrl": "http://localhost:8000"
    }
  }
}

日本語インターフェースの場合:

"env": {
  "CRAWL4AI_LANG": "ja"
}

📖 ドキュメント

言語別ドキュメント

• English: docs/ ディレクトリ

• 日本語: docs/ja/ ディレクトリ

🛠️ ツール概要

Webクローリング (3)

• crawl_url - JavaScriptサポート付きでWebページコンテンツを抽出

• deep_crawl_site - 設定可能な深さでサイト内の複数ページをクロール

• crawl_url_with_fallback - アンチボットサイト向けのフォールバック戦略を用いたクロール

データ抽出 (3)

• intelligent_extract - LLMを使用してWebページから特定のデータを抽出

• extract_entities - Webページからエンティティ（メールアドレス、電話番号など）を抽出

• extract_structured_data - CSSセレクターまたはLLMを使用して構造化データを抽出

YouTube (4)

• extract_youtube_transcript - タイムスタンプ付きでYouTubeの文字起こしを抽出

• batch_extract_youtube_transcripts - 複数のYouTube動画から文字起こしを抽出（最大3件）

• get_youtube_video_info - YouTube動画のメタデータと文字起こしの可用性を取得

• extract_youtube_comments - ページネーション付きでYouTube動画のコメントを抽出

検索 (4)

• search_google - ジャンルフィルタリングを使用してGoogle検索を実行

• batch_search_google - 複数のGoogle検索を実行（最大3件）

• search_and_crawl - Google検索を実行し、上位の結果をクロール

• get_search_genres - 利用可能な検索ジャンルを取得

ファイル処理 (3)

• process_file - PDF、Word、Excel、PowerPoint、ZIPをMarkdownに変換

• get_supported_file_formats - サポートされているファイル形式と機能を取得

• enhanced_process_large_content - チャンク分割とBM25フィルタリングを使用して大きなコンテンツを処理

バッチ操作 (2)

• batch_crawl - フォールバック付きで複数のURLをクロール（最大3 URL）

• multi_url_crawl - パターンベースの設定でマルチURLクロール（最大5 URLパターン）

💾 大規模な結果をディスクに保存 (token-saver)

すべての情報収集ツールは、オプションの output_path パラメータを受け付けます。これにより、取得したコンテンツ全体を直接ディスクに書き込み、メタデータのみの軽量なレスポンスを返します。これにより、LLMはコンテキスト制限を気にすることなく、巨大なページ、長いYouTubeの文字起こし、または大量のバッチ処理を実行でき、必要なときにのみ保存されたファイルから読み取ることができます。

仕組み:

• 単一ファイルツール（例: crawl_url, extract_youtube_transcript）は1つの .md（JSON系ツールは .json）を書き込みます。絶対ファイルパスを渡してください。拡張子が省略された場合は自動的に追加されます。既存の通常ファイルがある場合、overwrite=true でない限り拒否されます。

• バッチツール（batch_crawl, multi_url_crawl, deep_crawl_site, search_and_crawl, batch_extract_youtube_transcripts）は絶対ディレクトリパスを期待し、URLごとに1つの .md ファイルと index.json を書き込みます。存在しないパスはディレクトリとして扱われ、作成されます（/tmp/run.v1 のようにドットを含む名前も含む）。パスがすでに通常ファイルとして存在する場合、呼び出しは拒否されます。batch_crawl / multi_url_crawl はリスト形式の戻り値を維持し、各成功アイテムに output_file キーを埋め込みます。

• リクエスト辞書ツール（search_google, batch_search_google, search_and_crawl, batch_extract_youtube_transcripts）は、リクエスト辞書から直接永続化キーを読み取ります。

• 共通パラメータ: output_path（絶対パス。None または "" で永続化をスキップ）、include_content_in_response（デフォルト false。true の場合、コンテンツもレスポンスに含まれますが、content_limit/content_offset/max_content_per_page によるスライス制限の対象となります）、overwrite（デフォルト false）。

• 書き込みはファイル単位でアトミックに行われます（一時ファイル + os.replace）。親ディレクトリは自動的に作成されます。スライスやツール内部の切り捨てが行われる前の完全なペイロードが永続化されるため、レスポンスがスライスされていてもディスク上のコピーは常に完全です。

• バッチ辞書ツール（deep_crawl_site, search_and_crawl, batch_extract_youtube_transcripts）は、success=false と報告されたアイテムの永続化をスキップします。これらは index.json に file: null として表示されるため、呼び出し元は試行リストについて判断できます。

Markdown単一ファイルの例:

{
  "tool": "crawl_url",
  "arguments": {
    "url": "https://example.com/long-article",
    "output_path": "/tmp/crawl_out/article.md"
  }
}

JSON構造化抽出（拡張子自動追加）:

{
  "tool": "extract_structured_data",
  "arguments": {
    "url": "https://example.com/products",
    "extraction_type": "css",
    "css_selectors": {"price": ".price", "name": "h1"},
    "output_path": "/tmp/crawl_out/products"
  }
}

バッチディレクトリモード:

{
  "tool": "batch_crawl",
  "arguments": {
    "urls": ["https://a.example", "https://b.example"],
    "output_path": "/tmp/crawl_out/batch_run1"
  }
}

永続化された各Markdownファイルは、url、title、fetched_at、source_tool を含むYAMLフロントマターブロックで始まり、アーティファクトが自己記述的になるようにしています。

🎯 一般的なユースケース

コンテンツリサーチ:

search_and_crawl → extract_structured_data → analysis

ドキュメントマイニング:

deep_crawl_site → batch processing → extraction

メディア分析:

extract_youtube_transcript → summarization workflow

サイトマッピング:

batch_crawl → multi_url_crawl → comprehensive data

🚨 クイックトラブルシューティング

インストールに関する問題:

1. 適切な権限でセットアップスクリプトを再実行する

2. 開発用インストール方法を試す

3. ブラウザの依存関係がインストールされているか確認する

パフォーマンスに関する問題:

• JavaScriptを多用するサイトには wait_for_js: true を使用する

• 読み込みが遅いページにはタイムアウトを増やす

• ターゲットを絞った抽出には extract_structured_data を使用する

設定に関する問題:

• claude_desktop_config.json のJSON構文を確認する

• ファイルパスが絶対パスであることを確認する

• 設定変更後にClaude Desktopを再起動する

🏗️ プロジェクト構造

• オリジナルライブラリ: crawl4ai (unclecode)

• MCPラッパー: このリポジトリ (walksoda)

• 実装: 非公式のサードパーティ統合

📄 ライセンス

このプロジェクトはcrawl4aiライブラリの非公式ラッパーです。基盤となる機能については、元の crawl4aiライセンス を参照してください。

🤝 貢献

貢献ガイドラインと開発セットアップ手順については、開発ガイド を参照してください。

🔗 関連プロジェクト

• crawl4ai - 基盤となるWebクローリングライブラリ

• Model Context Protocol - このサーバーが実装する標準

• Claude Desktop - MCPサーバーの主要クライアント