site-crawler-mcp

サイト全体をクロールするMCPサーバーで、crawl4ai（Apache-2.0）をベースに構築されています。 検索エンジンのスパイダー（BFS）のようにウェブサイトのすべての内部リンクをクロールし、 公開時間 / タイトル / URLでページをフィルタリングし、クロールしたページに対して操作（要約、リンククリック、ファイルダウンロード）を行うことができます。 結果はJSONとして返され、SQLiteに永続化され、後続のプロジェクトで再利用できます。

中文简介：一个「像谷歌爬虫一样」的全站内链爬虫 MCP。基于 crawl4ai 自研封装， 支持 BFS 全站遍历、时间/标题/URL 筛选、页面操作（LLM 概括/点击链接/下载文件）、 结果 JSON 返回 + SQLite 持久化。注册到 Reasonix / Claude Desktop / Cursor 等任意 MCP 客户端即可全局复用。

機能

• ✅ サイト全体のBFSクロール — すべての内部リンクを巡回（max_depth / max_pages を制御可能）

• ✅ 時間フィルタ — ページのメタ / JSON-LD / URL から公開時間を抽出し、 利用できない場合はクロール時間をフォールバック（結果には time_source がタグ付けされます）

• ✅ タイトルフィルタ — タイトルのキーワードで包含 / 除外（大文字小文字を区別しない）

• ✅ URLパターン＆ドメインフィルタ — glob/regex URLマッチング、同一ドメイン制限

• ✅ 礼儀正しいクロール — デフォルトで robots.txt を尊重し、レート制限を実施（切り替え可能）

• ✅ ページ操作 — LLMによる要約（LiteLLM: DeepSeek / GLM / OpenAI…、ローカルフォールバック）、 特定のリンクのクリック（CSSセレクタまたはリンクテキスト）、ファイルのダウンロード

• ✅ SQLite永続化 — query_crawls ツールで、後のプロジェクトでクロールデータを再利用可能

Related MCP server: Spider MCP Server

ツール

要件

• Python ≥ 3.12（3.12.13でテスト済み）

• uv 推奨（オプション — 通常の pip でも動作します）

• Playwright ブラウザ: python -m playwright install chromium （または PLAYWRIGHT_BROWSERS_PATH を既存のブラウザインストールに指定）

インストールと登録

# 1. Create environment & install
uv venv .venv --python 3.12
uv pip install --python .venv\Scripts\python.exe crawl4ai "mcp>=1.2,<2"
uv pip install --python .venv\Scripts\python.exe -e .

# 2. Install browser (once)
.venv\Scripts\python.exe -m playwright install chromium

# 3. Register as MCP server (example for Reasonix config.toml)
[[plugins]]
name    = "site-crawler-mcp"
type    = "stdio"
command = "C:\\path\\to\\site-crawler-mcp\\.venv\\Scripts\\python.exe"
args    = ["-m", "site_crawler_mcp.server"]

Claude Desktop / Cursor の場合、設定ファイルの mcpServers の下に同じ command/args を追加してください。

クイックスタート（Python API）

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python", args=["-m", "site_crawler_mcp.server"])
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            res = await session.call_tool("crawl_site", {
                "start_url": "https://example.com",
                "max_depth": 2,
                "max_pages": 20,
                "title_contains": "Example",
            })
            print(res.content[0].text)

asyncio.run(main())

時間フィルタの仕組み

crawl4aiのURLフィルタはURLのみで機能するため、コンテンツレベルのフィルタリングはここで実装されています：

1. URLレベルの絞り込み — TimeRangeFilter / TitleFilter（URLの日付パターン、URLキーワード）

2. コンテンツレベル — 各ページが取得された後、公開時間は <meta property="article:published_time">、JSON-LD datePublished、<time datetime>、 または URL 内の YYYY/MM/DD から抽出されます。見つからない場合はクロール時間が使用されます（判断は time_source として文書化されます）。

コンプライアンス

• デフォルトで robots.txt とレート制限を尊重し、対象サイトへの負荷やIP禁止を避けます。

• 学習用 / 研究用 / 自身のサイト向けです。対象サイトの利用規約と現地の法律に従ってください。

ライセンス

MIT

crawl4ai（Apache-2.0）をベースに構築されています。