Fetcher MCP

基于 Playwright 无头浏览器的网页内容抓取 MCP 服务器

🌟 推荐工具: OllaMan - 强大的 Ollama AI 模型管理平台

核心优势

JavaScript 支持: 与传统爬虫不同，Fetcher MCP 通过 Playwright 执行 JavaScript，可完美处理动态网页内容和现代 Web 应用。
智能内容提取: 内置 Readability 算法自动提取网页主体内容，过滤广告、导航栏等非核心元素。
灵活输出格式: 支持 HTML 和 Markdown 两种输出格式，便于与各类下游应用集成。
并行处理能力: fetch_urls 工具支持多 URL 并发抓取，显著提升批量操作效率。
资源优化: 自动屏蔽非必要资源（图片、样式表、字体、媒体），降低带宽消耗并提升性能。
健壮的错误处理: 完善的错误处理与日志记录机制，确保在问题页面场景下仍能可靠运行。
可配置参数: 提供超时设置、内容提取、输出格式等细粒度控制，适应不同使用场景。

快速开始

通过 npx 直接运行：

npx -y fetcher-mcp

首次使用时需安装浏览器环境，在终端执行以下命令：

npx playwright install chromium

HTTP 与 SSE 传输协议

使用 --transport=http 参数可同时启动可流式传输的 HTTP 端点和 SSE 端点服务：

npx -y fetcher-mcp --log --transport=http --host=0.0.0.0 --port=3000

启动后服务器提供以下端点：

/mcp - 可流式传输的 HTTP 端点（现代 MCP 协议）
/sse - SSE 端点（传统 MCP 协议）

客户端可根据需求选择连接方式。

调试模式

添加 --debug 选项运行可显示浏览器窗口用于调试：

npx -y fetcher-mcp --debug

配置 MCP

在 Claude Desktop 中配置此 MCP 服务器：

MacOS 路径：~/Library/Application Support/Claude/claude_desktop_config.json

Windows 路径：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fetcher": {
      "command": "npx",
      "args": ["-y", "fetcher-mcp"]
    }
  }
}

Docker 部署

Docker 运行

docker run -p 3000:3000 ghcr.io/jae-jae/fetcher-mcp:latest

Docker Compose 部署

创建 docker-compose.yml 文件：

version: "3.8"

services:
  fetcher-mcp:
    image: ghcr.io/jae-jae/fetcher-mcp:latest
    container_name: fetcher-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    # Using host network mode on Linux hosts can improve browser access efficiency
    # network_mode: "host"
    volumes:
      # For Playwright, may need to share certain system paths
      - /tmp:/tmp
    # Health check
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3

然后执行：

docker-compose up -d

功能特性

fetch_url - 从指定 URL 获取网页内容
- 使用 Playwright 无头浏览器解析 JavaScript
- 支持智能提取主体内容并转换为 Markdown
- 支持以下参数：
  - url: 目标网页 URL（必填参数）
  - timeout: 页面加载超时时间（毫秒），默认 30000（30 秒）
  - waitUntil: 判定导航完成的条件，可选：'load', 'domcontentloaded', 'networkidle', 'commit'，默认为 'load'
  - extractContent: 是否智能提取主体内容，默认为 true
  - maxLength: 返回内容最大长度（字符数），默认无限制
  - returnHtml: 是否返回 HTML 内容而非 Markdown，默认为 false
  - waitForNavigation: 是否等待初始加载后的额外导航（适用于反爬验证站点），默认为 false
  - navigationTimeout: 等待额外导航的最长时间（毫秒），默认 10000（10 秒）
  - disableMedia: 是否禁用媒体资源（图片、样式表、字体、媒体），默认为 true
  - debug: 是否启用调试模式（显示浏览器窗口），若指定将覆盖 --debug 命令行标志
fetch_urls - 并行批量获取多个网页内容
- 采用多标签页并行抓取提升性能
- 返回合并结果并清晰分隔不同网页内容
- 支持以下参数：
  - urls: 待抓取的 URL 数组（必填参数）
  - 其他参数与 fetch_url 相同

实用技巧

特殊网站处理方案

应对反爬机制

等待完全加载：对于使用验证码、重定向等机制的网站，可在提示中包含：
```
请等待页面完全加载
```
这将启用 waitForNavigation: true 参数。
延长超时时间：针对加载缓慢的网站：
```
请将页面加载超时设为60秒
```
系统会相应调整 timeout 和 navigationTimeout 参数。

内容获取调整

保留原始 HTML 结构：当内容提取可能失败时：
```
请保留原始HTML内容
```
设置 extractContent: false 和 returnHtml: true。
获取完整页面内容：当提取内容过于局限时：
```
请获取完整网页内容而非仅主体内容
```
设置 extractContent: false。
返回 HTML 格式：当需要 HTML 而非默认 Markdown 时：
```
请返回HTML格式内容
```
设置 returnHtml: true。

调试与认证

启用调试模式

动态调试激活：在特定抓取操作中显示浏览器窗口：
```
请为此抓取操作启用调试模式
```
即使服务器未使用 --debug 标志启动，也会设置 debug: true。

使用自定义 Cookie 认证

手动登录：使用自有凭证登录时：
```
请启用调试模式以便我手动登录网站
```
设置 debug: true 或使用 --debug 标志，保持浏览器窗口开放供手动登录。
调试浏览器交互：调试模式启用后：
1. 浏览器窗口保持打开状态
2. 可使用凭证手动登录网站
3. 登录完成后将使用认证会话获取内容
为特定请求启用调试：即使服务器已在运行，也可为特定请求启用调试：
```
请为此认证步骤启用调试模式
```
仅对该请求设置 debug: true，打开浏览器窗口供手动登录。

开发指南

安装依赖

npm install

安装 Playwright 浏览器

安装 Playwright 所需的浏览器环境：

npm run install-browser

构建服务器

npm run build

调试方法

使用 MCP Inspector 进行调试：

npm run inspector

也可启用可视化浏览器模式进行调试：

node build/index.js --debug

开源协议

基于 MIT 许可证授权

Translation Not Available Yet