CrawlEyes MCP Server

CrawlEyes — AI エージェント向けウェブスクレイピング＆検索ツールキット

英語 | 中国語

CrawlEyes は、AI エージェントに信頼性の高い全文抽出（web_extract）と堅牢な検索（web_search）のバックエンドを提供します。エージェントがウェブを見て読むための「目」となるツールです。Hermes Agent を対象に構築・テストされています。

さらに、標準 MCP サーバーとしても利用できるため、あらゆる MCP クライアント（Claude Desktop、Cursor、その他のエージェント）が、同じ検索・抽出機能を再利用できます。

CrawlEyes を選ぶ理由

ほとんどのエージェントツールキットは、パイプラインの一部分しかカバーしていません。CrawlEyes は、外部アカウントなしで中国のグレート・ファイアウォールの内側でも実際に運用できる、まれなオールインワンツールキットです。

	一般的なエージェントツールキット	CrawlEyes
🔍 検索	API キーが必要で、中国ではブロックされることも多い	✅ SearXNG（セルフホスト）＋ Tavily のキー不要フォールバック — 設定不要、キー不要
📄 抽出	独立したスクレイパー、または Firecrawl SaaS	✅ Crawl4AI による組み込みの全文抽出、ノイズを約89％除去
🧠 セマンティック再ランク付け	ほとんど含まれない	✅ ローカルの fastembed による再ランク付け — torch 不要、モデルは約50MB
🔌 MCP サーバー	含まれていないことが多い	✅ 標準 MCP ツール（search ＋ extract ＋ deep_research ＋ sitemap）、あらゆるクライアントに対応
🌐 中国での利用に適した設計	主に英語対応／GFW によるブロックあり	✅ 中国本土の実サーバーでテスト済み（baidu ＋ yandex）

API キー不要。外部アカウント不要。コマンドを1つ実行するだけ。 CrawlEyes は、検索＋抽出＋セマンティック再ランク付け＋MCP を、中国での利用に適したセルフホスト可能な単一パッケージに統合した、この分野で唯一のツールキットです。

機能

機能	場所	重要な理由
全文抽出	scripts/crawl4ai_cli.py	ヘッドレスブラウザーでスクレイピングし、クリーンな Markdown に変換します。JS／動的コンテンツ／UA によるブロックがあるページの約 80％に対応します
コンテンツのノイズ除去（P1）	crawl4ai_cli.py --noise-filter	Crawl4AI の PruningContentFilter でナビゲーション／広告／コメントを削除します。一般的な記事で**24.6k→2.8k 文字（ノイズを約 89％除去）**を実測しています
バックオフ付きリトライ（P3）	crawl4ai_cli.py --retry N	一時的なエラーが発生した場合に指数バックオフ（1s／2s／4s）で再試行します
ブラウザーセッションの再利用（P4）	crawl4ai_cli.py --session NAME	1 つのプロセス内でスクレイピング間のブラウザーコンテキストを再利用し、URL ごとのコールドスタートをなくします
キーワードに焦点を当てた抽出	crawl4ai_cli.py --bm25 KEYWORD	キーワードに関連する段落のみを保持します（実験的機能です。BM25 は英語中心のため、英語のドキュメントで最もよく機能します）
検索（主）	SearXNG（セルフホスト可能なメタ検索）	プライバシーに配慮した検索アグリゲーターです
検索（フォールバック）	Tavily キーレス API	SearXNG が停止または結果なしの場合に使える、設定不要で API キーも不要なフォールバックです
検索オーケストレーション	plugins/searxng-tavily/	Hermes プラグインプロバイダーです。まず SearXNG を使用し、自動的に Tavily キーレスへフォールバックします。3 状態サーキットブレーカー（3 回失敗 → 60s のクールダウン → ハーフオープン）と共有 SQLite キャッシュ（TTL 3600s）を備えます
セマンティック再ランキング（P2）	scripts/crawl_search_standalone.py	fastembed と BAAI/bge-small-zh-v1.5（512 次元、torch 依存なし、約 50MB、キャッシュ済み）を使用して、検索結果をローカルの埋め込みで再ランキングします。関連性の高い結果を先頭に表示します。実測では、クローラーに関連する項目は 0.817／0.732 で上位に浮上し、関連性のない項目は 0.302／0.139 で下位に沈みました
MCP サーバー（P5）	scripts/mcp_crawl_server.py	search + extract + deep_research + sitemap を標準の MCP ツールとして公開します（デフォルトは stdio。リモートクライアントには streamable-http も使用できます）。Hermes に依存せず、あらゆる MCP クライアントで動作します。抽出したコンテンツはプロンプトインジェクション対策としてサニタイズされます（不可視文字とプロンプト乗っ取りの行を除去します）。統合レート制限 + 指数バックオフにより、すべてのツールを保護します（スライディングウィンドウ、ツールごとのコスト）。これにより、エージェントからの同時呼び出しが下流サービスに過剰な負荷をかけることを防ぎます
サイトマップの検出（P1）	crawleyes/sitemap.py	sitemap(origin) → sitemap.xml（通常形式／gzip／インデックス再帰）を解析し、フォールバックとして robots.txt を参照して、重複のない URL マップを返します。サイト全体の取得やディープリサーチの初期データに使うサイトの URL 全体を、API キーなしで検出できます
複数形式での抽出（P0）	extract(..., format=)	markdown（デフォルト）／fit（ノイズ除去済み）／raw（フィルターなし）／markdown_with_citations から、必要なクリーンアップレベルを選べます
RAG 対応インターフェース	crawleyes/rag.py	1 行の markdown(url)／search_markdown(query) で、RAG コーパス向けのクリーンでサニタイズ済みの LLM 対応 Markdown を取得できます
ディープリサーチ	crawleyes/deep_research.py	deep_research(topic) → トピックをサブ質問に分解 → 検索 → 抽出 → 出典付き Markdown レポートを合成します。オプションで LLM（OpenAI 互換エンドポイントならどれでも使用可能）を利用でき、LLM がない場合は根拠集約モードで動作します
検証	scripts/	Hermes プロファイルごとに各バックエンドをエンドツーエンドで検証する、シンプルなサブプロセススクリプトです

プロジェクト構成

plugins/searxng-tavily/   Hermes web-search provider plugin (SearXNG → Tavily keyless fallback)
                          + three-state circuit breaker + shared SQLite cache
scripts/
  crawl4ai_cli.py          Universal scraping CLI (URL → Markdown), with denoise/retry/session/BM25
  crawl_search_standalone.py  Standalone search (SearXNG → Tavily) + optional semantic rerank.
                             No Hermes dependency — usable anywhere, powers the MCP server.
  mcp_crawl_server.py      Standard MCP server exposing search + extract + deep_research + sitemap (stdio)
  single_env_check.py      Verify crawl4ai provider registered+available+extracts (one profile)
  verify_searxng_tavily.py Verify searxng-tavily provider: normal path + forced fallback
  agent_link_check.py      Verify full agent tool chain: web_search_tool dispatch + logs

クイックスタート

1. Crawl4AI をインストールする（中国国内向けミラー）

python3 -m venv .venv
# Use Tsinghua PyPI mirror for speed (or any mirror you prefer)
.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple crawl4ai
# Playwright browser kernel — use npmmirror binary mirror if cdn.playwright.dev is blocked
PLAYWRIGHT_DOWNLOAD_HOST=https://registry.npmmirror.com/-/binary/playwright \
  .venv/bin/python -m playwright install chromium
.venv/bin/crawl4ai-setup

2. ページをスクレイピングする

.venv/bin/python scripts/crawl4ai_cli.py https://example.com          # stdout Markdown
.venv/bin/python scripts/crawl4ai_cli.py https://example.com -o out.md  # to file
.venv/bin/python scripts/crawl4ai_cli.py URL --text --max-words 5000   # plain text, truncated

# Multi-format extraction (markdown|fit|raw|markdown_with_citations)
.venv/bin/python scripts/crawl4ai_cli.py URL --format raw              # unfiltered source markdown
.venv/bin/python scripts/crawl4ai_cli.py URL --format markdown_with_citations  # + source URLs

# Respect robots.txt (opt-in, default off)
.venv/bin/python scripts/crawl4ai_cli.py URL --respect-robots

# Denoise nav/ads + retry 3x + reuse session across scrapes
.venv/bin/python scripts/crawl4ai_cli.py URL --noise-filter --retry 3 --session s1

3. 検索 + 再ランキングを使用する（Hermes 不要のスタンドアロン）

# Optional: local semantic rerank of results (fastembed + bge-small-zh, auto-downloaded)
.venv/bin/pip install -i https://pypi.tuna.tsinghua.edu.cn/simple fastembed

# SearXNG first, Tavily keyless fallback, then rerank
SEARXNG_URL=https://your-searxng .venv/bin/python -c "
import sys; sys.path.insert(0, 'scripts')
from crawl_search_standalone import CrawlSearch
r = CrawlSearch(rerank=True).search('your query')
print(r['data']['web'])"

中国のネットワークに関する注意：埋め込みモデルは HuggingFace からダウンロードされますが、中国本土のネットワークではブロックされています。HF_ENDPOINT=https://hf-mirror.com と HF_HUB_DISABLE_XET=1 を設定してください（hf-mirror は xet プロトコルをサポートしていないため、この設定がないと 401 が返されます）。

4. MCP サーバーとして実行する（あらゆるクライアントで使用可能）

# Any MCP client can connect via stdio (default):
.venv/bin/python scripts/mcp_crawl_server.py
# Exposes tools:
#   search(query, limit)                 - SearXNG → Tavily keyless, rerank, retry+rate-limit
#   extract(url, max_words, format)      - markdown|fit|raw|markdown_with_citations
#   deep_research(topic, num_questions)  - multi-round cited report
#   sitemap(origin, max_urls)            - URL map from sitemap.xml / robots.txt

# Or serve over HTTP (streamable-http) for remote clients:
.venv/bin/python -m crawleyes.mcp_crawl_server --transport http --port 8765 --host 127.0.0.1
#   → clients connect to http://127.0.0.1:8765/mcp
#   (host/port configurable; default 127.0.0.1:8765)

Hermes で使用する場合は、config.yaml に追加してください。

mcp_servers:
  crawl:
    command: "/path/to/crawl/.venv/bin/python"
    args: ["/path/to/crawl/scripts/mcp_crawl_server.py"]
    timeout: 90
    connect_timeout: 60

4b. Firecrawl 互換の /scrape エンドポイント

すでに Firecrawl の Python SDK をお使いですか？CrawlEyes を指定すれば、コードをそのまま使えます。

.venv/bin/python -m crawleyes.firecrawl_api --port 8899 --host 127.0.0.1
#   POST /v2/scrape  →  { success, data: { markdown, metadata } }
#   GET  /healthz    →  health check

from firecrawl import Firecrawl
fc = Firecrawl(api_url="http://127.0.0.1:8899", api_key="ignored")
doc = fc.scrape(url="https://example.com")   # → { markdown, metadata }

これは Firecrawl API の実用的なサブセットです。CrawlEyes 独自の抽出エンジンを基盤とし、コアとなる /scrape の仕様（success + data.markdown + data.metadata）を実装しています。Firecrawl の非同期 /crawl キュー、/search、/map は実装していません。理由については設計ノートをご覧ください。

5. 検索プラグインをインストールする（Hermes）

plugins/searxng-tavily/ を Hermes のプラグインディレクトリにコピーし、次を実行します。

hermes plugins enable web/searxng-tavily
hermes config set web.search_backend searxng-tavily

Hermes プロファイルの .env で SEARXNG_URL を設定し、SearXNG インスタンスを指定してください。未設定の場合、または接続できない場合は、プロバイダーが自動的に Tavily のキー不要 API にフォールバックします（API キーは不要です）。

注：このプラグインが適用されるのは、新しく開始したエージェントセッションのみです。

6. 検証する

# Requires the Hermes source tree + its venv
venv/bin/python scripts/verify_searxng_tavily.py $HERMES_HOME
venv/bin/python scripts/agent_link_check.py $HERMES_HOME

設計ノート

• 階層化された構成：すべてを網羅する単一のツールはありません。Crawl4AI が抽出を担い、SearXNG + Tavily が検索を担います。各レイヤーにはテスト済みのフォールバックがあります。
• Tavily のキー不要 API は設定不要、アカウント不要で動作し、検索経路全体に低コストの耐障害性をもたらします。
• サーキットブレーカーの対象は SearXNG のみ：Tavily へのフォールバックが成功しても、ブレーカーはリセットされません（そうしないと、ブレーカーが作動しなくなります）。record_success() が呼び出されるのは、SearXNG 自体が成功した場合のみです。
• 共有 SQLite キャッシュは、$HOME ではなく pwd.getpwuid を使って、実際のユーザーホームディレクトリに保存されます。$HOME は Hermes プロファイルによって上書きされるためです。これにより、すべてのプロファイルでひとつのキャッシュを共有できます。WAL + 5 秒のタイムアウト + try/except により、並行実行時にはキャッシュなしの状態へ安全に移行します。
• セマンティックな再ランキングは低コストです。fastembed（ONNX）を使うことで、約 2GB の torch 依存を回避できます。モデルはキャッシュ済みなら約 0.6 秒で読み込まれ、埋め込みの生成は約 50 ミリ秒です。
• MCP サーバーはスタンドアロンです。Hermes の内部機能をインポートしないため、Python 3.12 のどの環境でも動作し、あらゆる MCP クライアントにサービスを提供できます。
• MCP トランスポートは 2 種類に対応しています。stdio（デフォルトの標準的な MCP クライアント向け）または streamable-http（--transport http）を利用でき、同じコードベースでローカルプロセスとリモート HTTP クライアントの両方に対応します。
• レート制限は一元化され、階層的に適用されます。MCP ツールと、deep-research 内部の検索・抽出はすべて、ツールごとのコストを考慮した単一のスライディングウィンドウ型リミッターを共有します。これにより、複数ラウンドにわたる deep research の実行中でも、エージェントの並列呼び出しによって SearXNG／Tavily／Crawl4AI に過剰な負荷がかかることを防ぎます。

クレジットと着想元

このプロジェクトは、優れたオープンソースツールを基盤としています。ここにあるコードはすべて独自の実装であり、コードのコピーはありません。ただし、アイデアとインターフェースは以下のプロジェクトから着想を得ています。各プロジェクトの作者に心より感謝します。

このリポジトリの機能	着想元	ライセンス
抽出エンジン（Crawl4AI ラッパー）	Crawl4AI — 直接依存	Apache-2.0
コンテンツのノイズ除去（P1）	Readability、GeneralNewsExtractor（アイデア）	Apache-2.0 / MIT
セマンティック再ランキング（P2）	Vane、Perplexica（アイデア）	MIT / MIT
バックオフ付きリトライ（P3）	Crawlee（アイデア）	Apache-2.0
ブラウザーセッションの再利用（P4）	camoufox（アイデア）	MIT
MCP サーバー（P5）	playwright-mcp、exa-mcp-server（アイデア）	Apache-2.0 / MIT
検索オーケストレーション / フォールバック	SearXNG — セルフホスト（公式 Docker イメージを使用、ソースコードは変更せず）、HTTP API 経由のみでアクセス · Tavily keyless	AGPL-3.0（サーバーソフトウェア。リンク／埋め込みなし） / プロプライエタリ API

設計の独立性：ここでの実装は一から作成しています。上記プロジェクトのアプローチ（ノイズ除去のしきい値、再ランキングのパイプライン、バックオフ戦略、MCP ツールのパターン）は調査しましたが、ソースコードはコピーしていません。依存関係は requirements.txt で宣言しています。クレジットの記載に不足や誤りがある場合は、Issue を作成してください。

コンプライアンス

CrawlEyes は、正当な調査や個人利用を目的とする汎用フェッチツールキットです。プロキシプール、フィンガープリントのローテーション、CAPTCHA の解決（スクレイピング対策の回避）は意図的に含めていません。これらは対象範囲外です。

Robots.txt の確認はオプトイン方式（デフォルトではオフ）です。extract / markdown に respect_robots=True を渡す（または CLI で --respect-robots を指定する）と、各対象サイトの robots.txt（RFC 9309）を確認し、明示的に拒否されている URL を拒否します。正当なスクレイピングが厳しすぎる、または不具合のある robots ルールによって気づかないうちにブロックされないよう、デフォルトではオフにしています。ユースケースに応じたコンプライアンスの判断は、呼び出し元が行います。大規模なスクレイピングを行う前に、必ず各サイトの利用規約を確認してください。

ライセンス

MIT — LICENSE を参照してください。

---

📮 フォローはこちら

公式アカウント：AI Aperture —— AI エンジニアリングの実践、多数のエージェントを用いたシステム、オープンソースプロジェクトの経験を共有しています。

QR コードをスキャンしてフォローすると、プロジェクトの更新情報や技術コンテンツをご覧いただけます。