JinDaGe - scraper-mcp MCP Details

article

README

🚀 Scraper MCP

Scraper MCP 是一个针对上下文进行优化的模型上下文协议（MCP）服务器，专为高效网络数据抓取而设计。该服务器能够为人工智能工具提供经过预处理和筛选的网页内容，通过将原始 HTML 转换为 Markdown 或纯文本，并在服务器端应用 CSS 选择器，大幅减少了大语言模型（LLM）所需处理的令牌数量，确保其仅接收真正需要的数据。

🚀 快速开始

选项 1：使用 Docker Run（最简单方式）

从 Docker Hub 或 GitHub Container Registry 拉取并运行预构建的镜像：

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

# 或者使用 GitHub Container Registry
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 界面）

✨ 主要特性

上下文优化

CSS 选择器过滤：在将内容发送给大语言模型之前，在服务器端提取相关内容（例如 .article-content, #main）。
智能转换：将 HTML 转换为 Markdown 或纯文本，消除标记噪声。
链接提取：返回结构化的链接对象，而非原始的 HTML 锚标签。
精准抓取：结合 CSS 选择器和 strip_tags 进行精确过滤。
令牌高效：与原始 HTML 相比，可减少 70 - 90% 的上下文窗口使用量。

抓取工具与基础设施

多种抓取模式：支持原始 HTML、Markdown 转换、纯文本提取和链接提取。
批量操作：通过自动重试逻辑并发处理多个 URL。
智能缓存：采用三层缓存系统（实时/默认/静态），减少冗余请求。
重试与恢复：使用指数退避算法，可配置重试次数以处理临时故障。
可扩展架构：支持多种抓取后端，设计具有扩展性。

监控与管理

实时仪表盘：监控服务器健康状况、请求统计信息、缓存指标和最近的错误。
交互式测试平台：可直接在浏览器中测试抓取工具，并实时查看 JSON 响应。
运行时配置：无需重启服务器，即可调整并发数、超时时间、重试次数、缓存 TTL 和代理设置。
Docker 支持：使用 Docker Compose 一键部署。
HTTP/SSE 传输：支持可流式 HTTP 和 SSE MCP 传输。

📦 安装指南

环境设置

在项目根目录下创建一个 .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           # 为单页应用启用（默认：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 文件。

💻 使用示例

基础用法

在 Claude Code 中尝试以下操作：

> scrape https://cutler.sg/
~ 抓取主页，可能默认进行 Markdown 转换

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

> scrape and filter all <title> elements from those urls
~ 从所有约 100 个 URL 中仅提取标题

高级用法

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

# ✅ Scraper MCP：服务器端过滤 + 转换
from scraper_mcp import scrape_url_markdown
scrape_url_markdown(
    "https://blog.example.com/article",
    css_selector="article.main-content"  # 仅提取文章内容
)
# 结果：2.5KB 的 Markdown → 约 2,500 个令牌

📚 详细文档

可用工具

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：找到的链接总数

从 Claude Desktop 连接

要在 Claude Desktop 中使用此服务器，需要将其添加到 MCP 设置中：

{
  "mcpServers": {
    "scraper": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

连接成功后，Claude 可以使用所有四种抓取工具。你可以通过在浏览器中打开 http://localhost:8000/ 访问仪表盘，实时监控请求。

仪表盘特性

访问监控仪表盘 http://localhost:8000/，可以实时监控和管理你的抓取器。

实时监控仪表盘

一眼就能跟踪服务器健康状况、请求统计信息、重试指标和缓存性能：仪表盘

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

交互式 API 测试平台

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

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

运行时配置

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

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

为什么选择上下文友好的抓取方式？

传统的网络抓取方式将原始 HTML 发送给大语言模型，会在标记、脚本和无关内容上浪费 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 发送给大语言模型
import requests
html = requests.get("https://blog.example.com/article").text
# 结果：45KB 的 HTML → 约 45,000 个令牌

# ✅ Scraper MCP：服务器端过滤 + 转换
from scraper_mcp import scrape_url_markdown
scrape_url_markdown(
    "https://blog.example.com/article",
    css_selector="article.main-content"  # 仅提取文章内容
)
# 结果：2.5KB 的 Markdown → 约 2,500 个令牌

主要优势

大量节省令牌：每次请求可降低 10 - 20 倍的成本。
更大的上下文窗口：在相同的上下文中可以容纳 18 倍的内容。
更快的处理速度：减少数据传输和处理量。
更干净的数据：预过滤、结构化的内容，便于分析。
更高的准确性：大语言模型专注于相关内容，而不是标记噪声。

何时使用每个工具

scrape_url_markdown：文章、文档、博客文章（最适合大语言模型使用）
scrape_url_text：纯文本内容，无需太多格式
scrape_extract_links：导航、链接分析、站点地图生成
scrape_url（原始 HTML）：需要保留精确结构或提取元标签时使用

🔧 技术细节

本地开发

前提条件

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 Container Registry：

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 8000:8000 scraper-mcp:custom

# 或者使用 docker-compose.yml（修改 image 行以使用 scraper-mcp:custom）
docker-compose up -d

项目结构

scraper-mcp/
├── src/scraper_mcp/
│   ├── __init__.py
│   ├── __main__.py
│   ├── server.py                  # 主 MCP 服务器入口点
│   ├── admin/                     # 管理 API（配置、统计、缓存）
│   │   ├── router.py              # HTTP 端点处理程序
│   │   └── service.py             # 业务逻辑
│   ├── dashboard/                 # Web 仪表盘
│   │   ├── router.py              # 仪表盘路由
│   │   └── templates/
│   │       └── dashboard.html     # 监控 UI
│   ├── tools/                     # MCP 抓取工具
│   │   ├── router.py              # 工具注册
│   │   └── service.py             # 抓取实现
│   ├── models/                    # Pydantic 数据模型
│   │   ├── scrape.py              # 抓取请求/响应模型
│   │   └── links.py               # 链接提取模型
│   ├── providers/                 # 抓取后端提供者
│   │   ├── base.py                # 抽象提供者接口
│   │   └── requests_provider.py  # HTTP 提供者（requests 库）
│   ├── core/
│   │   └── providers.py           # 提供者注册表和选择
│   ├── cache.py                   # 请求缓存（基于磁盘）
│   ├── cache_manager.py           # 缓存生命周期管理
│   ├── metrics.py                 # 请求/重试指标跟踪
│   └── utils.py                   # HTML 处理实用工具
├── tests/                         # Pytest 测试套件
│   ├── test_server.py
│   ├── test_tools.py
│   └── test_utils.py
├── .github/workflows/
│   ├── ci.yml                     # CI/CD：测试、代码检查
│   └── docker-publish.yml         # Docker 镜像发布
├── Dockerfile                     # 多阶段生产构建
├── docker-compose.yml             # 本地开发设置
├── pyproject.toml                 # Python 依赖（uv）
├── .env.example                   # 环境配置模板
└── README.md

架构

服务器采用提供者架构，支持多种抓取后端：

ScraperProvider：抓取实现的抽象接口
RequestsProvider：使用 requests 库的基本 HTTP 抓取器
未来提供者：可以添加对 Playwright、Selenium、Scrapy 等的支持提供者的选择基于 URL 模式自动进行，便于为不同类型的网站添加专门的提供者。

重试行为与错误处理

抓取器包含智能重试逻辑，采用指数退避算法处理临时故障：

重试配置

默认最大重试次数：3 次尝试
默认超时时间：30 秒
重试延迟：从 1 秒开始的指数退避

重试计划

对于默认配置（max_retries=3）：

第一次尝试：立即执行
第一次重试：等待 1 秒
第二次重试：等待 2 秒
第三次重试：等待 4 秒最终失败前的最大总等待时间约为 7 秒。

触发重试的情况

抓取器在以下情况下会自动重试：

网络超时（requests.Timeout）
连接失败（requests.ConnectionError）
HTTP 错误（4xx、5xx 状态码）

重试元数据

所有成功响应的元数据中都包含重试信息：

{
  "attempts": 2,      // 总尝试次数（1 表示无重试）
  "retries": 1,       // 重试次数
  "elapsed_ms": 234.5 // 请求总时间（毫秒）
}

自定义重试行为

# 禁用重试
from scraper_mcp import scrape_url
import asyncio
result = asyncio.run(scrape_url("https://example.com", max_retries=0))

# 对于不稳定的网站进行更积极的重试
result = asyncio.run(scrape_url("https://example.com", max_retries=5, timeout=60))

# 对于对时间敏感的操作进行快速失败
result = asyncio.run(scrape_url("https://example.com", max_retries=1, timeout=10))

CSS 选择器过滤

所有抓取工具都支持可选的 CSS 选择器过滤，在处理之前从 HTML 中提取特定元素，让你能够专注于所需的内容。

支持的选择器

服务器使用 BeautifulSoup4 的 .select() 方法（由 Soup Sieve 提供支持），支持以下选择器：

标签选择器：meta, img, a, div
多个选择器：img, video（用逗号分隔）
类选择器：.article-content, .main-text
ID 选择器：#header, #main-content
属性选择器：a[href], meta[property="og:image"], img[src^="https://"]
后代组合器：article p, div.content a
伪类：p:nth-of-type(3), a:not([rel])

使用示例

# 仅提取元标签用于 SEO 分析
from scraper_mcp import scrape_url
scrape_url("https://example.com", css_selector="meta")

# 获取文章内容的 Markdown 格式，排除广告
from scraper_mcp import scrape_url_markdown
scrape_url_markdown("https://blog.com/article", css_selector="article.main-content")

# 从特定部分提取文本
from scraper_mcp import scrape_url_text
scrape_url_text("https://example.com", css_selector="#main-content")

# 仅获取产品图片
scrape_url("https://shop.com/product", css_selector="img.product-image, img[data-product]")

# 仅提取导航链接
from scraper_mcp import scrape_extract_links
scrape_extract_links("https://example.com", css_selector="nav.primary")

# 获取 Open Graph 元标签
scrape_url("https://example.com", css_selector='meta[property^="og:"]')

# 结合 strip_tags 进行精细控制
scrape_url_markdown(
    "https://example.com",
    css_selector="article",  # 首先过滤到文章部分
    strip_tags=["script", "style"]  # 然后移除脚本和样式
)

工作原理

抓取：从 URL 获取 HTML
过滤（如果提供了 css_selector）：应用 CSS 选择器，仅保留匹配的元素
处理：转换为 Markdown/纯文本或提取链接
返回：在元数据中包含 elements_matched 计数

CSS 选择器的好处

减少噪声：仅提取相关内容，忽略广告、导航栏和页脚
范围提取：仅从特定部分获取链接（例如，主内容部分，而非侧边栏）
高效：处理更少的 HTML，获得更干净的结果
可组合：可与 strip_tags 一起使用，实现最大程度的控制

环境变量

使用 Docker 运行时，可以使用环境变量配置服务器：

TRANSPORT：传输类型（streamable-http 或 sse，默认值为 streamable-http）
HOST：绑定的主机，默认值为 0.0.0.0
PORT：绑定的端口，默认值为 8000
ENABLE_CACHE_TOOLS：启用缓存管理工具（true, 1, 或 yes 启用，默认值为 false）
- 启用后，将暴露 cache_stats, cache_clear_expired, 和 cache_clear_all 工具
- 默认情况下为安全和简单起见禁用

代理配置

抓取器通过标准环境变量支持 HTTP/HTTPS 代理。当在企业防火墙后运行或需要通过特定代理路由流量时，这非常有用。

使用 Docker Compose 配置代理

在项目根目录下创建一个 .env 文件（参考 .env.example）：

# 非 SSL 请求的 HTTP 代理
HTTP_PROXY=http://proxy.example.com:8080
http_proxy=http://proxy.example.com:8080

# SSL 请求的 HTTPS 代理
HTTPS_PROXY=http://proxy.example.com:8080
https_proxy=http://proxy.example.com:8080

# 绕过特定主机的代理（用逗号分隔）
NO_PROXY=localhost,127.0.0.1,.local
no_proxy=localhost,127.0.0.1,.local

然后启动服务：

docker-compose up -d

Docker Compose 会自动读取 .env 文件，并在构建时（用于包安装）和运行时（用于 HTTP 请求）将变量传递给容器。

使用 Docker Run 配置代理

docker run -p 8000:8000 \
  -e HTTP_PROXY=http://proxy.example.com:8080 \
  -e HTTPS_PROXY=http://proxy.example.com:8080 \
  -e NO_PROXY=localhost,127.0.0.1,.local \
  scraper-mcp:latest

带认证的代理

如果你的代理需要认证，请在 URL 中包含凭证：

HTTP_PROXY=http://username:password@proxy.example.com:8080
HTTPS_PROXY=http://username:password@proxy.example.com:8080

构建时与运行时代理

代理配置在两个阶段起作用：

构建时：用于 Docker 安装包（apt、uv、pip）
运行时：用于抓取器进行 HTTP 请求同时支持大写和小写变量名（例如 HTTP_PROXY 和 http_proxy）。

验证代理配置

检查容器日志以验证是否正在使用代理设置：

docker-compose logs scraper-mcp

requests 库会自动遵循这些环境变量，并将所有 HTTP/HTTPS 流量通过配置的代理路由。

ScrapeOps 代理集成

抓取器可选集成 ScrapeOps，这是一个高级代理服务，可帮助绕过反爬虫措施、渲染 JavaScript 并访问地理限制的内容。当提供 API 密钥时，ScrapeOps 会自动启用。

什么是 ScrapeOps？

ScrapeOps 提供以下功能：

JavaScript 渲染：抓取单页应用和动态内容
住宅代理：降低被阻止的可能性
地理定位：访问特定国家的内容
反爬虫绕过：自动轮换头部和指纹识别
高成功率：智能重试和优化

启用 ScrapeOps

只需将你的 API 密钥添加到 .env 文件中：

# 从 https://scrapeops.io/ 获取你的 API 密钥
SCRAPEOPS_API_KEY=your_api_key_here

就这么简单！所有抓取请求将自动通过 ScrapeOps 路由。无需对你的 MCP 工具或代码进行任何更改。

配置选项

使用环境变量自定义 ScrapeOps 的行为（完整参考请查看 .env.example）：

# 为单页应用启用 JavaScript 渲染（默认：false）
SCRAPEOPS_RENDER_JS=true

# 使用住宅代理而非数据中心代理（默认：false）
SCRAPEOPS_RESIDENTIAL=true

# 目标特定国家（可选）
SCRAPEOPS_COUNTRY=us

# 保留原始头部而非进行优化（默认：false）
SCRAPEOPS_KEEP_HEADERS=true

# 用户代理轮换的设备类型（默认：desktop）
SCRAPEOPS_DEVICE=mobile

完整示例配置

# .env 文件
SCRAPEOPS_API_KEY=your_api_key_here
SCRAPEOPS_RENDER_JS=true
SCRAPEOPS_RESIDENTIAL=true
SCRAPEOPS_COUNTRY=us
SCRAPEOPS_DEVICE=desktop

📄 许可证

本项目采用 MIT 许可证授权。

最后更新时间：2025 年 10 月 31 日