site-crawler-mcp

Ein seitenweiter Crawler MCP Server basierend auf crawl4ai (Apache-2.0). Es crawlt jeden internen Link einer Website wie eine Suchmaschinen-Spinne (BFS), filtert Seiten nach Veröffentlichungszeit / Titel / URL und kann auf gecrawlten Seiten Operationen durchführen (zusammenfassen, Links klicken, Dateien herunterladen). Ergebnisse werden als JSON zurückgegeben und in SQLite gespeichert, um sie von jedem Projekt wiederzuverwenden.

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

Features

• ✅ Seitenweiter BFS-Crawl — durchläuft alle internen Links (max_depth / max_pages steuerbar)

• ✅ Zeitfilter — extrahiert Veröffentlichungszeit aus Seiten-Meta / JSON-LD / URL zuerst, fällt auf Crawl-Zeit zurück, wenn nicht verfügbar (Ergebnis mit time_source markiert)

• ✅ Titelfilter — ein-/ausschließen nach Titel-Schlüsselwort (groß-/kleinschreibungsunabhängig)

• ✅ URL-Muster & Domain-Filter — Glob/Regex-URL-Abgleich, Einschränkung auf gleiche Domain

• ✅ Höfliches Crawling — respektiert standardmäßig robots.txt und Rate-Limits (umschaltbar)

• ✅ Seitenoperationen — LLM-Zusammenfassung (LiteLLM: DeepSeek / GLM / OpenAI…, lokaler Fallback), Klick auf einen bestimmten Link (CSS-Selektor oder Linktext), Dateien herunterladen

• ✅ SQLite-Persistenz — query_crawls-Tool zur Wiederverwendung von gecrawlten Daten in späteren Projekten

Related MCP server: Spider MCP Server

Tools

Requirements

• Python ≥ 3.12 (getestet auf 3.12.13)

• uv empfohlen (optional — einfaches pip funktioniert auch)

• Playwright-Browser: python -m playwright install chromium (oder PLAYWRIGHT_BROWSERS_PATH auf eine vorhandene Browser-Installation setzen)

Install & Register

# 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"]

Für Claude Desktop / Cursor fügen Sie die gleichen command/args unter mcpServers in deren Konfigurationsdateien hinzu.

Quick Start (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())

How the time filter works

crawl4ai's URL-Filter arbeiten nur auf URLs, daher wird hier inhaltsbezogenes Filtern implementiert:

1. URL-Ebene-Bereinigung — TimeRangeFilter / TitleFilter (URL-Datumsmuster, URL-Schlüsselwörter)

2. Inhaltsebene — nach dem Abrufen jeder Seite wird die Veröffentlichungszeit aus <meta property="article:published_time">, JSON-LD datePublished, <time datetime>, oder YYYY/MM/DD in der URL extrahiert. Wenn keine gefunden wird, wird die Crawl-Zeit verwendet (Entscheidung als time_source dokumentiert).

Compliance

• Respektiert standardmäßig robots.txt und Rate-Limits, um Zielseiten nicht zu belasten oder IP-Sperren zu riskieren.

• Für Lern-/Forschungs-/eigene Websites; bitte befolgen Sie die AGB der Zielseiten und lokale Gesetze.

License

MIT

Basiert auf crawl4ai (Apache-2.0).