site-crawler-mcp

一个基于 crawl4ai (Apache-2.0) 构建的全站爬虫 MCP 服务器。 它像搜索引擎蜘蛛（BFS）一样爬取网站的所有内部链接，按发布时间/标题/URL 过滤页面，并可对爬取页面进行操作（摘要、点击链接、下载文件）。 结果以 JSON 返回并持久化到 SQLite，供任何项目复用。

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

功能特性

• ✅ 全站 BFS 爬取 — 遍历所有内部链接（可控制 max_depth / max_pages）

• ✅ 时间筛选 — 优先从页面 meta / 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) 构建。