功能	描述
认证爬取	使用 Firefox 会话令牌访问已登录页面。
浏览器自动化	回退到 Playwright 处理动态内容或登录表单。
域名白名单	仅爬取与逗号分隔的域名列表匹配的 URL。
深度限制爬取	可配置的爬取深度（1-9 层）。
正则搜索	在爬取内容或索引中搜索正则模式。
文档解析	从 PDF、DOCX、XLSX 和 TXT 文件中提取文本。
实时流式传输	结果以 JSONL 格式流式传输（按页面分块）。
索引	将结果按域名存储在 JSON 文件中，供后续搜索使用。
速率限制	强制每秒 5 个请求，最多 5 个线程。
恢复支持	可以从检查点恢复中断的爬取。
会话验证	验证令牌范围以防止滥用。

📦 安装

先决条件

Python 3.9+（推荐：3.11+）。
Firefox（浏览器自动化所需）。
系统库（用于文档解析）：
- PDF：poppler-utils（Linux）或 pdfminer.six（跨平台）。
- DOCX/XLSX：python-docx、openpyxl。

步骤

1. 克隆仓库

git clone https://github.com/bpweatherill/WebSearchAndCrawl.git
cd WebSearchAndCrawl

2. 设置虚拟环境

python -m venv venv
source venv/bin/activate  # Linux/Mac
# OR
venv\Scripts\activate   # Windows

3. 安装依赖

pip install -r requirements.txt

4. 安装 Playwright 浏览器

playwright install firefox

5.（可选）配置环境变量

在项目根目录创建一个 .env 文件：

# Server
MCP_PORT=8808
MCP_HOST=0.0.0.0

# Crawler
MAX_DEPTH=9
MAX_THREADS=5
RATE_LIMIT=5
REQUEST_TIMEOUT=10
MAX_MEMORY_MB=1024

# Firefox
FIREFOX_PROFILE=my_profile  # Optional: Specific Firefox profile
DEFAULT_SEARCH_ENGINE=google

# Directories
INDEX_DIR=./index
DOWNLOADS_DIR=./downloads
CHECKPOINTS_DIR=./checkpoints

🏃 使用方法

1. 启动 MCP 服务器

python -m server.main

服务器将在 http://localhost:8808 上启动（或 .env 中指定的端口）。

2. MCP 工具（HTTP 端点）

所有工具都返回 JSON 响应，并支持 流式传输 以获取实时结果。

端点	方法	描述	请求体
`/crawl_website`	POST	爬取网站并流式传输结果。	CrawlRequest
`/search_index`	POST	在本地索引中搜索正则匹配。	SearchIndexRequest
`/download_documents`	POST	下载与正则匹配的文档。	DownloadRequest
`/get_search_results`	POST	使用 Firefox 的搜索引擎获取结果。	WebSearchRequest
`/list_indexed_domains`	GET	列出所有已索引内容的域名。	-
`/health`	GET	健康检查。	-

请求/响应模式

CrawlRequest

{
  "url": "https://www.nasa.gov",
  "whitelist_domains": "nasa.gov",
  "max_depth": 3,
  "use_token": false,
  "firefox_profile": "my_profile"
}

url：爬取的起始 URL。
whitelist_domains：允许的域名列表，以逗号分隔（例如，"nasa.gov,spacex.com"）。
max_depth：最大爬取深度（1-9）。
use_token：如果可用，使用 Firefox 会话令牌。
firefox_profile：Firefox 配置文件名称（可选）。

流式响应（JSONL）：

{
  "excerpt": "NASA's Perseverance Rover lands on Mars...",
  "full_text": "Full article text here...",
  "url": "https://www.nasa.gov/mars2020",
  "timestamp": "2024-05-20T12:00:00Z",
  "domain": "nasa.gov"
}

---.

SearchIndexRequest

{
  "domain": "nasa.gov",
  "regex": ".*Mars.*",
  "max_results": 10
}

domain：要搜索的域名（例如，"nasa.gov"）。
regex：要匹配的正则表达式。
max_results：要返回的最大结果数。

响应：

[
  {
    "url": "https://www.nasa.gov/mars2020",
    "excerpt": "NASA's Perseverance Rover lands on Mars...",
    "timestamp": "2024-05-20T12:00:00Z"
  }
]

---。

DownloadRequest

{
  "domain": "nasa.gov",
  "regex": ".*\\.pdf$",
  "output_dir": "./downloads/nasa.gov"
}

domain：要下载的域名。
regex：要下载的文件的正则表达式（例如，"*.pdf"）。
output_dir：自定义输出目录（可选）。

流式响应（JSONL）：

{
  "filename": "./downloads/nasa.gov/mars_rover.pdf",
  "url": "https://www.nasa.gov/pdf/mars_rover.pdf",
  "parsed_text": "Extracted text from PDF..."
}

---。

WebSearchRequest

{
  "query": "NASA Mars missions",
  "search_engine": "google",
  "use_token": false,
  "firefox_profile": "my_profile"
}

query：搜索查询。
search_engine：搜索引擎（默认：Firefox 默认）。
use_token：如果可用，使用 Firefox 会话令牌。
firefox_profile：Firefox 配置文件名称（可选）。

流式响应（JSONL）：

{
  "title": "Mars 2020 Mission - NASA",
  "url": "https://www.nasa.gov/mars2020",
  "snippet": "Learn about the Perseverance Rover..."
}

🔍 示例

1. 爬取 NASA.gov 并索引结果

curl -X POST http://localhost:8808/crawl_website \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.nasa.gov",
    "whitelist_domains": "nasa.gov",
    "max_depth": 2,
    "use_token": false
  }'

2. 搜索索引内容中的 "Mars"

curl -X POST http://localhost:8808/search_index \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "nasa.gov",
    "regex": ".*Mars.*",
    "max_results": 5
  }'

3. 从 NASA.gov 下载 PDF

curl -X POST http://localhost:8808/download_documents \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "nasa.gov",
    "regex": ".*\\.pdf$"
  }'

4. 使用 Firefox 搜索 Google

curl -X POST http://localhost:8808/get_search_results \
  -H "Content-Type: application/json" \
  -d '{
    "query": "NASA Mars missions",
    "search_engine": "google"
  }'

📁 项目结构

WebSearchAndCrawl/
│
├── server/                          # Core server logic
│   ├── __init__.py
│   ├── main.py                       # FastAPI app + MCP tools
│   ├── config.py                     # Configuration settings
│   ├── schemas.py                    # Pydantic request/response models
│   │
│   ├── firefox/                      # Firefox browser automation
│   │   ├── __init__.py
│   │   ├── controller.py              # Playwright Firefox management
│   │   └── token_manager.py           # Session token handling
│   │
│   ├── crawler/                     # Web crawling logic
│   │   ├── __init__.py
│   │   ├── crawler.py                # Main crawling logic
│   │   └── rate_limiter.py            # Thread/rate limiting
│   │
│   ├── indexer/                     # Indexing and search
│   │   ├── __init__.py
│   │   ├── indexer.py                 # JSON index management
│   │   └── search_engine.py           # Regex search
│   │
│   ├── downloader/                  # Document downloading and parsing
│   │   ├── __init__.py
│   │   ├── downloader.py              # Download logic
│   │   └── parsers/                  # File type parsers
│   │       ├── __init__.py
│   │       ├── pdf_parser.py
│   │       ├── docx_parser.py
│   │       └── xlsx_parser.py
│   │
│   └── streamer.py                   # Chunked JSON streaming
│
├── tests/                           # Unit and integration tests
│   ├── __init__.py
│   ├── test_firefox.py
│   └── test_crawler.py
│
├── index/                           # Index files (auto-generated)
│   ├── nasa.gov.json
│   └── ...
│
├── downloads/                       # Downloaded documents (auto-generated)
│   ├── nasa.gov/
│   │   ├── document1.pdf
│   │   └── ...
│   └── ...
│
├── checkpoints/                     # Crawl checkpoints (auto-generated)
│   └── ...
│
├── requirements.txt                 # Python dependencies
├── .env.example                     # Example environment variables
└── README.md                        # This file

⚙️ 配置

环境变量

变量	默认值	描述
`MCP_PORT`	`8808`	HTTP 服务器端口。
`MCP_HOST`	`0.0.0.0`	HTTP 服务器主机。
`MAX_DEPTH`	`9`	最大爬取深度（1-9）。
`MAX_THREADS`	`5`	最大并发线程数。
`RATE_LIMIT`	`5`	每秒最大请求数。
`REQUEST_TIMEOUT`	`10`	请求超时时间（秒）。
`MAX_MEMORY_MB`	`1024`	最大内存使用量（MB）。
`FIREFOX_PROFILE`	`None`	Firefox 配置文件名称（可选）。
`DEFAULT_SEARCH_ENGINE`	`google`	默认搜索引擎。
`INDEX_DIR`	`./index`	索引文件目录。
`DOWNLOADS_DIR`	`./downloads`	下载文件目录。
`CHECKPOINTS_DIR`	`./checkpoints`	爬取检查点目录。

🛡️ 安全注意事项

会话令牌：
- 令牌 仅存储在内存中（不持久化到磁盘）。
- 令牌范围 经过验证 以防止滥用（例如，用于 nasa.gov 的令牌不能用于 evil.com）。
输入清理：
- 所有输入（URL、正则表达式等）均经过清理 以防止注入攻击。
速率限制：
- 强制 每秒 5 个请求 和 最多 5 个线程，以避免压垮服务器。
robots.txt 合规性：
- 爬虫遵守 robots.txt 并跳过不允许的 URL。
白名单：
- 仅爬取与 白名单域名 匹配的 URL。

🚀 增强功能（路线图）

增强功能	描述	优先级
持久化令牌	将令牌存储在加密文件中，以便在重启后持久化。	中
完整的 `robots.txt` 解析	正确解析 `robots.txt` 规则，而不是简单的检查。	中
高级分页处理	检测并跟踪分页链接（例如，"下一页" 按钮）。	高
懒加载支持	检测并触发懒加载内容（例如，无限滚动）。	高
检查点	保存爬取状态以恢复中断的爬取。	高
全文搜索	除正则外，支持全文搜索。	低
数据库后端	用 SQLite/PostgreSQL 替换 JSON 文件以实现可扩展性。	低
分布式爬取	支持使用多个工作进程进行水平扩展。	低
Docker 支持	添加 `Dockerfile` 以支持容器化部署。	中
认证辅助工具	内置支持常见认证方法（OAuth、SAML）。	中
代理支持	添加代理支持，以便在防火墙后爬取。	低
自定义请求头	允许用户为请求指定自定义请求头。	中
Webhook 通知	当发现新结果时通知 webhook URL。	低

🤝 贡献指南

分叉（Fork）仓库。
创建功能分支（git checkout -b feature/your-feature）。
提交您的更改（git commit -m "Add your feature"）。
推送到分支（git push origin feature/your-feature）。
打开拉取请求（Pull Request）。

📜 许可证

本项目根据 MIT 许可证 授权。有关详细信息，请参阅 LICENSE。

📞 支持

问题：在 GitHub Issues 标签页中报告错误或请求功能。
讨论：加入 GitHub Discussions 进行问答。

🏆 致谢

Playwright：用于浏览器自动化。
FastAPI：用于 HTTP 服务器。
pdfminer.six：用于 PDF 解析。
python-docx/openpyxl：用于 Office 文件解析。

This server cannot be deployed

Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

Maintenance

ActivityMaintained

ResponsivenessSyncing

Resources

Related MCP Connectors

Aginx Browser A
net.aginx
Stealth web browser for agents: search, fetch, click, download and type in persistent MCP sessions.
Browser Automation Agent Orchestration
155
https://browser.aginx.net/mcp
luminati-io-brightdata-mcp
ai.smithery
One MCP for the Web. Easily search, crawl, navigate, and extract websites without getting blocked.…
Browser Automation Web Scraping Search
2
https://server.smithery.ai/@luminati-io/brightdata-mcp/mcp
MESSORA A
dev.messora
Scrape, crawl and search the web for AI agents via MCP.
Web Scraping Browser Automation Search
1
https://mcp.messora.dev/mcp
ReplyNodes C
com.replynodes
Web MCP: scrape/crawl sites, web search, brand assets, app stores, YouTube, Reddit, Hacker News.
Browser Automation Web Scraping Search
7314
https://mcp.replynodes.com/mcp

Related MCP Servers

web-scraper-server
Browser Automation Web Scraping
ImYourBoyRoy
A
license
C
quality
C
maintenance
Provides browser automation and web scraping as MCP tools, enabling autonomous URL ingestion, crawling, extraction, and anti-bot handling with interactive browser control.
Updated 3 months ago (2026-08-03 15:17 UTC)
62
6
MIT
Scout MCP Serverofficial
Browser Automation Web Scraping Search
Scout-AI-Labs
A
license
Not graded
quality
D
maintenance
Enables web search, scraping, extraction, and crawling through an MCP interface, allowing coding agents to access real-time web data.
Updated 4 months ago (2026-06-21 09:51 UTC)
1
MIT
OpenCode Web Audit MCP
Web Scraping Browser Automation Search
humbertolvarona
A
license
Not graded
quality
D
maintenance
A read-only Python MCP server for authorized website research, structured data extraction, downloadable-document analysis, and content auditing inside OpenCode. It crawls authorized public domains with safety constraints including robots.txt respect, SSRF defenses, bounded concurrency, and content-type allowlists.
Updated 3 months ago (2026-08-03 22:22 UTC)
MIT
webharvest
Browser Automation Web Scraping Search
dan-rozhkov
A
license
Not graded
quality
B
maintenance
Enables web search and scraping through MCP, running locally with courtesy rate limiting and caching.
Updated a day ago (2026-11-01 23:05 UTC)
13 npm
MIT

WebSearchAndCrawl

🚀 用途

🔧 功能

📦 安装

先决条件

步骤

1. 克隆仓库

2. 设置虚拟环境

3. 安装依赖

4. 安装 Playwright 浏览器

5.（可选）配置环境变量

🏃 使用方法

1. 启动 MCP 服务器

2. MCP 工具（HTTP 端点）

请求/响应模式

CrawlRequest

SearchIndexRequest

DownloadRequest

WebSearchRequest

🔍 示例

1. 爬取 NASA.gov 并索引结果

2. 搜索索引内容中的 "Mars"

3. 从 NASA.gov 下载 PDF

4. 使用 Firefox 搜索 Google

📁 项目结构

⚙️ 配置

环境变量

🛡️ 安全注意事项

🚀 增强功能（路线图）

🤝 贡献指南

📜 许可证

📞 支持

🏆 致谢

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

web-scraper-server

Scout MCP Serverofficial

OpenCode Web Audit MCP

webharvest