crawl4ai-mcp

MCP-Crawl4AI

Crawl4AI を活用したウェブクローリング用の Model Context Protocol サーバー

概要

MCP-Crawl4AI は、AI システムがライブウェブにアクセスできるようにする Model Context Protocol サーバーです。FastMCP v3 と Crawl4AI を基盤としており、ライフスパン管理されたヘッドレス Chromium ブラウザーを利用し、標準化された MCP インターフェースを通じて 4 つのツール、2 つのリソース、3 つのプロンプトを提供します。

実行時の依存関係は 2 つだけです — fastmcp と crawl4ai。

ヒント

ドキュメントサイト全文 →

主な機能

• FastMCP v3 による完全な MCP 準拠と、ツールのアノテーション（readOnlyHint、destructiveHint など）
• 4 つの目的に特化したツール。標準的なスクレイピング／クロールと、セッションのライフサイクル／成果物を中心に構成
• 3 つのプロンプト。一般的な LLM ワークフロー（要約、スキーマ抽出、ページ比較）向け
• 2 つのリソース。サーバー設定とバージョン情報を公開
• ヘッドレス Chromiumをライフスパンのシングルトンとして管理（一度起動すれば、すべての処理で再利用）
• 複数のトランスポート — stdio（デフォルト）と Streamable HTTP
• LLM 向けに最適化された出力 — マークダウン、クリーニング済み HTML、生 HTML、またはプレーンテキスト
• 標準的なオプショングループ。抽出、ランタイム、診断、セッション、レンダリング、巡回向け
• 1 つの crawl コントラクトで、リスト巡回と詳細巡回に対応
• セッション対応ワークフロー。明示的なセッション終了と成果物取得のツールを提供
• ブラウザーを自動セットアップ — Playwright ブラウザーがない場合に検出し、自動でインストール

インストール

pip install mcp-crawl4ai
mcp-crawl4ai --setup       # one-time: installs Playwright browsers

uv add mcp-crawl4ai
mcp-crawl4ai --setup       # one-time: installs Playwright browsers

docker build -t mcp-crawl4ai .
docker run -p 8000:8000 mcp-crawl4ai

git clone https://github.com/wyattowalsh/mcp-crawl4ai.git
cd mcp-crawl4ai
uv sync --group dev
mcp-crawl4ai --setup

メモ

サーバーは初回起動時に Playwright ブラウザーがないか自動検出し、自動インストールを試みます。mcp-crawl4ai --setup または crawl4ai-setup をいつでも手動で実行できます。

クイックスタート

mcp-crawl4ai

mcp-crawl4ai --transport http --port 8000

{
  "mcpServers": {
    "crawl4ai": {
      "command": "mcp-crawl4ai",
      "args": ["--transport", "stdio"]
    }
  }
}

claude mcp add crawl4ai -- mcp-crawl4ai --transport stdio

npx @modelcontextprotocol/inspector uv --directory . run mcp-crawl4ai

ツール

標準のインターフェースで公開されるツールは4 つです：

scrape

1 つの URL、または上限付きの URL リスト（最大 20 件）をスクレイピングし、標準形式の単一エンベロープレスポンスを返します。

• 入力：targets（str | list[str]）と、任意のグループ化された options
• 抽出（schema、extraction_mode）、ランタイム制御、診断、セッション設定、レンダリング設定、成果物の取得に対応
• schema_version、tool、ok、data/items、meta、warnings、error を含む標準 JSON エンベロープを返します

crawl

標準の巡回制御でクロールします。

• options.traversal.mode="list" は、上限付きのリスト巡回に使用します
• options.traversal.mode="deep" は、単一の起点から再帰的な BFS／DFS 巡回を行います
• scrape と同じエンベロープ形式を使用し、オプショングループと巡回オプションを共有します

close_session

options.session.session_id で作成したステートフルセッションを終了します。

get_artifact

options.conversion.capture_artifacts が有効な場合に、scrape または crawl 中に取得した成果物のメタデータ／内容を取得します。

コア機能と高度な使い方の選択

• コアの使い方（推奨）： 最小限のオプション（runtime、conversion.output_format、traversal.mode="list"）で scrape／crawl を使用します。ほとんどのエージェントワークフローで、動作の予測可能性を保ち、リスクを低減できます。
• 高度な使い方（明示的なオプトイン）： タスクの結果に必要な場合に限り、詳細巡回、カスタムディスパッチャー制御、JS トランスフォーム、抽出スキーマ、成果物の取得を使用します。
• 安全性の予算とゲート： 高度なオプションを有効にする前に、config://server の settings.defaults、settings.limits、settings.policies、settings.capabilities を確認し、有効な制約と機能ゲートを把握してください。

リソース

プロンプト

アーキテクチャ

graph TD
    A[MCP Client] -->|stdio / HTTP| B[FastMCP v3]
    B --> C[Tool Router]
    C --> D[scrape]
    C --> E[crawl]
    C --> F[close_session]
    C --> G[get_artifact]
    D & E & F & G --> N[AsyncWebCrawler Singleton]
    N --> O[Headless Chromium]
    B --> P[Resources]
    B --> Q[Prompts]

    style B fill:#4B8BBE,color:#fff
    style N fill:#FF6B35,color:#fff
    style O fill:#2496ED,color:#fff

このサーバーは単一モジュールのアーキテクチャを採用しています。

• FastMCP v3 が、MCP プロトコルのネゴシエーション、トランスポート、ツール／リソース／プロンプトの登録、メッセージのルーティングを処理します
• ライフスパン管理の AsyncWebCrawler が、サーバー起動時にヘッドレス Chromium ブラウザーを一度だけ起動してすべてのツール呼び出しで共有し、終了時に適切にシャットダウンします
• 4 つのツール関数を @mcp.tool() でデコレートし、正式なインターフェースを定義します
• 2 つのリソース関数を @mcp.resource() でデコレートし、JSON を返します
• 3 つのプロンプト関数を @mcp.prompt でデコレートし、構造化された Message リストを返します

重要

中間マネージャークラスやカスタム HTTP クライアントはありません。サーバーはすべてのクロールを crawl4ai の AsyncWebCrawler に、すべてのプロトコル処理を FastMCP に委任します。実行時の依存関係は 2 つだけです。

設定

テスト

# Run all tests
uv run pytest

# Coverage gate (>=90%)
uv run pytest --cov=mcp_crawl4ai --cov-report=term-missing

# Smoke tests only
uv run pytest -m smoke

# Unit tests only
uv run pytest -m unit

# Integration workflow tests
uv run pytest -m integration

# End-to-end workflow tests
uv run pytest -m e2e

# Manual live test (requires browser)
uv run python tests/manual/test_live.py

メモ

自動テストはすべて fastmcp.Client(mcp) を使用してメモリー内で実行されるため、ブラウザーやネットワークは必要ありません。テストスイートでは AsyncWebCrawler をモックし、高速で決定論的な実行を実現します。

コントリビューション

開発環境のセットアップ、コーディング規約、プルリクエストの手順については、コントリビューションガイドを参照してください。

ライセンス

このプロジェクトは MIT ライセンスのもとで公開されています。詳しくは LICENSE ファイルを参照してください。