Web Scrapper 服务 (MCP Stdin/Stdout & HTTP)

一个基于 Python 的 MCP 服务器，用于稳健的无头网页抓取——从网页中提取主要文本内容，并输出 Markdown、文本或 HTML，以实现与 AI 和自动化的无缝集成。

主要功能

• 无头浏览器抓取 (Playwright, BeautifulSoup, Markdownify)

• 输出 Markdown、文本或 HTML

• 专为 MCP (Model Context Protocol) stdio/JSON-RPC 集成设计

• 双重传输模式：stdio（默认）和用于共享服务模式的流式 HTTP

• 持久化浏览器池：Chromium 在请求间保持活跃，实现快速抓取

• 智能 DOM 等待：基于 MutationObserver 的内容稳定化，而非固定的 sleep 等待

• 容器化，提供预构建镜像

• 可通过环境变量配置

• 强大的错误处理（超时、HTTP 错误、Cloudflare 等）

• 基于域名的速率限制

• 易于与 AI 工具和 IDE 集成（Cursor, Claude Desktop, Continue, JetBrains, Zed 等）

• Cursor 一键安装，Claude 交互式安装

Related MCP server: Fetcher MCP

快速开始

使用 Docker 运行 (stdio 模式 — 每个客户端一个容器)

docker run -i --rm ghcr.io/justazul/web-scrapper-stdio

作为共享 HTTP 服务运行 (一个容器，多个客户端)

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -e BROWSER_POOL_SIZE=3 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

或者使用 Docker Compose：

docker compose --profile service up -d

一键安装 (Cursor IDE)

传输模式

stdio (默认)

每个 MCP 客户端通过 docker run -i 启动自己的容器。简单、零配置，适用于任何 MCP 客户端。

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

流式 HTTP (共享服务)

运行一个持久化容器，通过 HTTP 为多个 MCP 客户端提供服务。在运行多个 AI 工具实例（例如多个 Claude Code 会话）时可节省资源。

启动服务：

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

从你的 MCP 客户端连接：

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

与 AI 工具及 IDE 的集成

本服务支持与广泛的实现模型上下文协议 (MCP) 的 AI 工具和 IDE 集成。以下是针对最流行环境的即用型配置示例。根据需要替换镜像/标签以进行自定义构建。

Cursor IDE

添加到你的 .cursor/mcp.json (项目级) 或 ~/.cursor/mcp.json (全局)：

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Desktop

添加到你的 Claude Desktop MCP 配置中 (通常为 claude_desktop_config.json)：

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Code

添加到你的 .mcp.json 或全局 ~/.claude.json：

stdio 模式 (每个会话一个容器)：

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

HTTP 模式 (共享服务 — 先启动服务)：

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Continue (VSCode/JetBrains 插件)

添加到你的 continue.config.json 或通过 Continue 插件的 MCP 设置添加：

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

IntelliJ IDEA (JetBrains AI Assistant)

前往 Settings > Tools > AI Assistant > Model Context Protocol (MCP) 并添加一个新服务器。使用：

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/justazul/web-scrapper-stdio"
  ]
}

Zed 编辑器

添加到你的 Zed MCP 配置中 (查看 Zed 文档获取确切路径)：

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

使用方法

MCP 服务器 (工具/提示词)

此网页抓取器用作 MCP (Model Context Protocol) 工具，允许 AI 模型或其他自动化程序直接使用。

工具：scrape_web

参数：

• url (字符串，必填)：要抓取的 URL

• max_length (整数，可选)：返回内容的最大长度（默认：无限制）

• timeout_seconds (整数，可选)：页面加载的超时时间（秒）（默认：30）

• user_agent (字符串，可选)：直接传递给浏览器的自定义 User-Agent 字符串（默认为随机代理）

• wait_for_network_idle (布尔值，可选)：在抓取前等待网络活动稳定（默认：true）

• custom_elements_to_remove (字符串列表，可选)：提取前要移除的额外 HTML 元素（CSS 选择器）

• grace_period_seconds (浮点数，可选)：导航后等待 JS 渲染的时间。使用 MutationObserver 进行智能检测。设置为 0 可完全跳过。（默认：0.5）

• output_format (字符串，可选)：markdown、text 或 html（默认：markdown）

• click_selector (字符串，可选)：如果提供，在导航后和提取前点击匹配此选择器的元素

返回：

• 从网页提取的 Markdown 格式内容，以字符串形式返回

• 错误以 [ERROR] ... 开头的字符串形式报告

示例：使用 click_selector 和 custom_elements_to_remove

{
  "url": "http://uitestingplayground.com/clientdelay",
  "click_selector": "#ajaxButton",
  "grace_period_seconds": 10,
  "custom_elements_to_remove": [".ads-banner", "#popup"],
  "output_format": "markdown"
}

提示词：scrape

参数：

• url (字符串，必填)：要抓取的 URL

• output_format (字符串，可选)：markdown、text 或 html（默认：markdown）

返回：

• 以所选格式从网页提取的内容

注意：

• 默认返回 Markdown，但可以通过 output_format 请求文本或 HTML。

• 抓取器不检查 robots.txt，并将尝试获取提供的任何 URL。

• 不包含 REST API 或 CLI 工具；这是一个纯粹的 MCP stdio/JSON-RPC 工具。

• 抓取器始终提取网页的完整 <body> 内容，仅应用必要的噪音移除（移除 script、style、nav、footer、aside、header 等非内容标签）。抓取器会检测并处理 Cloudflare 挑战屏幕，并返回特定的错误字符串。

配置

你可以使用环境变量覆盖大多数配置选项：

核心设置

• DEFAULT_TIMEOUT_SECONDS：页面加载和导航的超时时间（默认：30）

• DEFAULT_MIN_CONTENT_LENGTH：提取文本的最小内容长度（默认：100）

• DEFAULT_MIN_CONTENT_LENGTH_SEARCH_APP：search.app 域名的最小内容长度（默认：30）

• DEFAULT_MIN_SECONDS_BETWEEN_REQUESTS：同一域名请求之间的最小延迟（默认：2）

• DEFAULT_GRACE_PERIOD_SECONDS：JS 渲染的默认宽限期（默认：0.5）

• DEBUG_LOGS_ENABLED：设置为 true 以启用调试级日志（默认：false）

浏览器池

• BROWSER_POOL_ENABLED：启用持久化浏览器池（默认：true）。设置为 false 可进行按需浏览器启动（原始行为）。

• BROWSER_POOL_SIZE：保持活跃的 Chromium 实例数量（默认：2）。每个实例占用约 100-200MB 内存。

传输

• MCP_TRANSPORT：传输模式 — stdio 或 streamable-http（默认：stdio）

• MCP_HTTP_PORT：使用 streamable-http 传输时的 HTTP 服务器端口（默认：8080）

• MCP_HTTP_HOST：HTTP 服务器绑定地址（默认：0.0.0.0）

Cloudflare 绕过

• CAPTCHA_API_KEY：验证码求解服务的 API 密钥。设置后，Cloudflare Turnstile 挑战将自动解决。为空（默认）时，受 CF 保护的页面将返回错误。

• CAPTCHA_PROVIDER：验证码求解提供商 — 2captcha、capsolver 或 capmonster（默认：2captcha）

• CAPTCHA_BASE_URL：自定义求解器 API 端点（默认：使用提供商的官方 URL）

• CAPTCHA_TIMEOUT：验证码求解的超时时间（秒）（默认：120）

测试设置

• DEFAULT_TEST_REQUEST_TIMEOUT：测试请求的超时时间（默认：10）

• DEFAULT_TEST_NO_DELAY_THRESHOLD：测试中跳过人工延迟的阈值（默认：0.5）

错误处理与限制

• 抓取器会检测并返回导航失败、超时、HTTP 错误（包括 404）和 Cloudflare 反机器人挑战的错误。

• 速率限制按域名执行（默认：请求之间间隔 2 秒）。

• Cloudflare 绕过：使用 Patchright (CDP 级反检测) 进行被动规避。大多数受 CF 保护的站点在抓取时不会触发挑战。当触发 Turnstile 挑战且设置了 CAPTCHA_API_KEY 时，它会通过第三方 API 自动解决。

• 限制：

  • 无 REST API 或 CLI 工具（仅限 MCP stdio/JSON-RPC）

  • 不支持非 HTML 内容（PDF、图像等）

  • 不支持受保护页面的身份验证或会话管理

  • 不适用于大规模抓取或违反网站条款的行为

开发与测试

运行测试 (Docker Compose)

所有测试必须使用 Docker Compose 运行。不要在 Docker 之外运行测试。

• 所有测试：

docker compose up --build --abort-on-container-exit test

• 仅 MCP 服务器测试：

docker compose up --build --abort-on-container-exit test_mcp

• 仅抓取器测试：

docker compose up --build --abort-on-container-exit test_scrapper

运行基准测试

docker compose run --rm benchmark

结果存储在 benchmarks/RESULTS.md 中。

贡献

欢迎贡献！请提交 issue 或 pull request 以进行错误修复、功能添加或改进。如果你计划进行重大更改，请先开启一个 issue 来讨论你的提议。

许可证

本项目采用 MIT 许可证 开源。