STARWARCLOUD STARWAR.AI
返回市场
爬取器-mcp

爬取器-mcp

作者：cotdp4 星标更新：2025-10-31
安装使用来源：spider==github.com

项目介绍

Scraper MCP

CI Docker Docker Hub GHCR

一个针对高效网络爬取优化的Model Context Protocol (MCP)服务器。此服务器为AI工具提供预处理和过滤过的网页内容，通过将原始HTML转换为markdown或文本，并在服务器端应用CSS选择器，减少了标记的使用，使得LLMs仅接收它们实际需要的数据。

使用Claude Code快速设置

从Docker Hub拉取并运行预构建的镜像：

# 使用Docker Hub
docker run -d -p 8000:8000 --name scraper-mcp cotdp/scraper-mcp:latest

# 将MCP服务器添加到Claude Code
claude mcp add --transport http scraper http://localhost:8000/mcp --scope user

# 查看日志
docker logs -f scraper-mcp

# 停止服务器
docker stop scraper-mcp && docker rm scraper-mcp

在Claude Code中试用：

> scrape https://cutler.sg/
~ 抓取首页，可能默认转换为markdown

> scrape and filter <url> 元素 from https://cutler.sg/sitemap.xml
~ 返回大约100个URL

> scrape and filter 所有 <title> 元素 from 这些URL
~ 仅获取来自约100个URL的标题

功能

上下文优化

  • CSS选择器过滤：在发送给LLM之前，仅提取相关的内容（例如，.article-content，#main）
  • 智能转换：将HTML转换为markdown或纯文本，消除标记噪音
  • 链接提取：返回结构化的链接对象，而不是原始HTML锚标签
  • 目标抓取：结合CSS选择器与strip_tags进行精确过滤
  • 标记效率：相比原始HTML，上下文窗口使用减少70-90%

抓取工具及基础设施

  • 多种抓取模式：原始HTML、markdown转换、纯文本提取和链接提取
  • 批处理操作：并发处理多个URL，并自动重试逻辑
  • 智能缓存：三级缓存系统（实时/默认/静态）以最小化冗余请求
  • 重试与弹性：对于瞬时失败，具有指数退避和可配置重试次数
  • 提供者架构：支持多种抓取后端的可扩展设计

监控与管理

  • 实时仪表板：监控服务器健康状况、请求统计、缓存指标和最近错误
  • 交互式沙箱：直接从浏览器测试抓取工具，实时返回JSON响应
  • 运行时配置：调整并发数、超时、重试次数、缓存TTL和代理设置，无需重启
  • Docker支持：使用Docker Compose一键部署
  • HTTP/SSE传输：支持Streamable HTTP和SSE MCP传输

仪表板功能

访问监控仪表板 http://localhost:8000/ 以实时监控和管理您的抓取器。

实时监控仪表板

跟踪服务器健康状况、请求统计、重试指标和缓存性能：

Dashboard

  • 服务器状态：健康指示器、运行时间和启动时间
  • 请求统计：总请求数、成功率和失败计数
  • 重试分析：总重试次数和每次请求平均重试次数
  • 缓存指标：条目数量、大小、命中率以及一键清除缓存
  • 最近请求：最后10次请求的时间戳、状态码和响应时间
  • 最近错误：最后10次失败的详细错误消息和尝试次数
  • 每9秒自动刷新一次以实现实时监控

交互式API沙箱

无需编写代码即可测试所有抓取工具：

Playground

  • 测试所有四个工具：scrape_url，scrape_url_markdown，scrape_url_text，scrape_extract_links
  • 配置参数：URL、超时、最大重试次数、CSS选择器
  • 查看带有语法高亮的格式化JSON响应
  • 一键复制到剪贴板
  • 查看执行时间以进行性能测试

运行时配置

无需重启服务器即可即时调整设置：

Config

  • 性能调优：并发数（1-50）、超时、最大重试次数
  • 缓存控制：默认、实时和静态缓存TTL设置
  • 代理设置：启用/禁用HTTP/HTTPS/NO_PROXY配置
  • 即时生效：更改立即生效，无需重启服务器
  • 非持久性：重启时设置会重置（使用.env进行永久更改）

为什么是上下文友好的抓取？

传统的网络抓取将原始HTML发送给LLMs，浪费了70-90%的上下文窗口在标记、脚本和无关内容上。Scraper MCP通过在服务器端进行繁重的工作解决了这个问题。

标记效率对比

无过滤（原始HTML）：

❌ 一篇典型博客文章45,000个标记
   - 40,000个标记：HTML标记、CSS、JavaScript、广告、导航
   - 5,000个标记：实际文章内容

使用Scraper MCP（CSS选择器+markdown）：

✅ 同样的内容2,500个标记
   - 0个标记：通过markdown转换消除了标记
   - 0个标记：通过CSS选择器过滤掉了广告/导航
   - 2,500个标记：干净的文章文本

结果：标记减少95%，相同上下文窗口内可以容纳18倍的内容

现实世界示例

# ❌ 传统方法：将原始HTML发送给LLM
html = requests.get("https://blog.example.com/article").text
# 结果：45KB的HTML → 大约45,000个标记

# ✅ Scraper MCP：服务器端过滤+转换
scrape_url_markdown(
    "https://blog.example.com/article",
    css_selector="article.main-content"  # 仅提取文章
)
# 结果：2.5KB的markdown → 大约2,500个标记

主要优势

  1. 大幅节省标记：每个请求的成本降低10-20倍
  2. 更大的上下文窗口：在相同的上下文中容纳18倍的内容
  3. 更快的处理速度：需要传输和处理的数据更少
  4. 更干净的数据：预过滤、结构化的数据，便于分析
  5. 更高的准确性：LLM专注于相关内容，而非标记噪音

何时使用每个工具

  • scrape_url_markdown：文章、文档、博客文章（最适合LLM消费）
  • scrape_url_text：纯文本内容，需要最少的格式化
  • scrape_extract_links：导航、链接分析、生成站点地图
  • scrape_url（原始HTML）：当您需要保留确切结构或提取元标签时

配置

环境设置

在项目根目录创建一个.env文件来配置服务器。从.env.example复制：

cp .env.example .env

关键配置选项

标准代理（用于企业防火墙）：

HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
NO_PROXY=localhost,127.0.0.1,.local

详见代理配置部分的详细设置说明。

ScrapeOps代理（用于JavaScript渲染、住宅IP、反机器人）：

SCRAPEOPS_API_KEY=your_api_key_here
SCRAPEOPS_RENDER_JS=true           # 启用SPA（默认：false）
SCRAPEOPS_RESIDENTIAL=true         # 使用住宅代理（默认：false）
SCRAPEOPS_COUNTRY=us               # 目标特定国家（可选）
SCRAPEOPS_DEVICE=desktop           # 设备类型：desktop|mobile|tablet

详见ScrapeOps代理集成部分的详细设置、使用案例和成本优化。

服务器设置（可选，默认设置适用于大多数情况）：

TRANSPORT=streamable-http          # 或 'sse'
HOST=0.0.0.0                       # 绑定到所有接口
PORT=8000                          # 默认端口
CACHE_DIR=/app/cache               # 缓存目录路径
ENABLE_CACHE_TOOLS=false           # 暴露缓存管理工具

详见.env.example中的完整配置参考及其详细注释。

快速开始

方案1：Docker Run（最简单）

从Docker Hub或GitHub容器注册表拉取并运行预构建的镜像：

# 使用Docker Hub
docker run -d -p 8000:8000 --name scraper-mcp cotdp/scraper-mcp:latest

# 或使用GitHub容器注册表
docker run -d -p  8000:8000 --name scraper-mcp ghcr.io/cotdp/scraper-mcp:latest

# 查看日志
docker logs -f scraper-mcp

# 停止服务器
docker stop scraper-mcp && docker rm scraper-mcp

服务器将在以下位置可用：

  • MCP端点：http://localhost:8000/mcp（供AI客户端使用）
  • 仪表板：http://localhost:8000/（Web界面）

方案2：Docker Compose（推荐用于生产）

为了持久存储、自定义配置和更容易的管理：

1. 创建一个docker-compose.yml文件：

services:
  scraper-mcp:
    image: cotdp/scraper-mcp:latest  # 或 ghcr.io/cotdp/scraper-mcp:latest
    container_name: scraper-mcp
    ports:
      - "8000:8000"
    environment:
      - TRANSPORT=streamable-http
      - HOST=0.0.0.0
      - PORT=8000
    volumes:
      - cache:/app/cache
    restart: unless-stopped

volumes:
  cache:

2. （可选）创建一个.env文件用于代理或ScrapeOps配置：

cp .env.example .env
# 编辑.env文件，填写您的代理或ScrapeOps设置

3. 启动服务器：

# 在分离模式下启动
docker-compose up -d

# 查看日志
docker-compose logs -f scraper-mcp

# 检查状态
docker-compose ps

4. 停止服务器：

# 停止并删除容器
docker-compose down

# 停止、删除容器并清除缓存卷
docker-compose down -v

服务器将在以下位置可用：

  • MCP端点：http://localhost:8000/mcp（供AI客户端使用）
  • 仪表板：http://localhost:8000/（Web界面）

可用工具

1. scrape_url

从URL抓取原始HTML内容。

参数：

  • urls（字符串或列表，必需）：要抓取的单个URL或URL列表（http://或https://）
  • timeout（整数，可选）：请求超时时间（秒，默认：30）
  • max_retries（整数，可选）：失败时的最大重试次数（默认：3）
  • css_selector（字符串，可选）：用于过滤HTML元素的CSS选择器（例如，“meta”，“img, video”，“.article-content”）

返回值：

  • url：重定向后的最终URL
  • content：原始HTML内容（如果提供了css_selector，则已过滤）
  • status_code：HTTP状态码
  • content_type：Content-Type头部值
  • metadata：附加元数据包括：
    • headers：响应头
    • encoding：内容编码
    • elapsed_ms：请求持续时间（毫秒）
    • attempts：总共尝试次数
    • retries：执行的重试次数
    • css_selector_applied：使用的CSS选择器（如果提供）
    • elements_matched：匹配的元素数量（如果提供了css_selector）

2. scrape_url_markdown

从URL抓取内容并将其转换为markdown格式。

参数：

  • urls（字符串或列表，必需）：要抓取的单个URL或URL列表（http://或https://）
  • timeout（整数，可选）：请求超时时间（秒，默认：30）
  • max_retries（整数，可选）：失败时的最大重试次数（默认：3）
  • strip_tags（数组，可选）：要剥离的HTML标签列表（例如，['script', 'style']）
  • css_selector（字符串，可选）：在转换前过滤HTML的CSS选择器（例如，“.article-content”，“article p”）

返回值：

  • 与scrape_url相同，但内容为markdown格式
  • metadata.page_metadata：提取的页面元数据（标题、描述等）
  • metadata.attempts：总共尝试次数
  • metadata.retries：执行的重试次数
  • metadata.css_selector_applied和metadata.elements_matched（如果提供了css_selector）

3. scrape_url_text

从URL抓取内容并提取纯文本内容。

参数：

  • urls（字符串或列表，必需）：要抓取的单个URL或URL列表（http://或https://）
  • timeout（整数，可选）：请求超时时间（秒，默认：30）
  • max_retries（整数，可选）：失败时的最大重试次数（默认：3）
  • strip_tags（数组，可选）：要剥离的HTML标签（默认：script, style, meta, link, noscript）
  • css_selector（字符串，可选）：在提取文本前过滤HTML的CSS选择器（例如，“#main-content”，“article.post”）

返回值：

  • 与scrape_url相同，但内容为纯文本
  • metadata.page_metadata：提取的页面元数据
  • metadata.attempts：总共尝试次数
  • metadata.retries：执行的重试次数
  • metadata.css_selector_applied和metadata.elements_matched（如果提供了css_selector）

4. scrape_extract_links

从URL抓取内容并提取所有链接。

参数：

  • urls（字符串或列表，必需）：要抓取的单个URL或URL列表（http://或https://）
  • timeout（整数，可选）：请求超时时间（秒，默认：30）
  • max_retries（整数，可选）：失败时的最大重试次数（默认：3）
  • css_selector（字符串，可选）：限定链接提取范围的CSS选择器（例如，“nav”，“article.main-content”）

返回值：

  • url：被抓取的URL
  • links：链接对象数组，包含url、text和title
  • count：找到的链接总数

本地开发

前提条件

  • Python 3.12+
  • uv 包管理器

设置

# 安装依赖
uv pip install -e ".[dev]"

# 本地运行服务器
python -m scraper_mcp

# 使用特定传输和端口运行
python -m scraper_mcp streamable-http 0.0.0.0 8000

开发命令

# 运行测试
pytest

# 类型检查
mypy src/

# 代码检查和格式化
ruff check .
ruff format .

Docker镜像

预构建镜像（推荐）

在每次发布时都会自动构建和发布的多平台镜像：

Docker Hub：

docker pull cotdp/scraper-mcp:latest

GitHub容器注册表：

docker pull ghcr.io/cotdp/scraper-mcp:latest

可用标签：

  • latest - 最新稳定版
  • 0.1.0，0.1，0 - 语义版本标签
  • main-<sha> - 最新的主分支构建

支持的平台：linux/amd64 和 linux/arm64

详见快速开始部分的使用说明。

从源代码构建

如果您需要定制镜像或本地构建：

# 克隆仓库
git clone https://github.com/cotdp/scraper-mcp.git
cd scraper-mcp

# 构建镜像
docker build -t scraper-mcp:custom .

# 使用默认设置运行
docker run -p