Puppeteer Vision MCP Server

](https://mseep.ai/app/djannot-puppeteer-vision-mcp)

木偶视觉MCP服务器

此模型上下文协议（MCP）服务器提供了一种工具，用于抓取网页并使用Puppeteer、Readability和Turndown将其转换为markdown格式。它具有人工智能驱动的交互功能，可以自动处理Cookie、验证码和其他交互元素。

现在可以通过以下方式轻松运行 npx!

特性

• 使用隐藏模式的Puppeter抓取网页
• 使用AI驱动的交互来自动处理：

- Cookie同意横幅 - 验证码 - 通讯或订阅提示 - 付费墙和登录墙 - 年龄验证提示 - 插播式广告 - 任何其他阻止内容的交互元素

• 使用Mozilla的可读性提取主要内容
• 将HTML转换为格式良好的Markdown
• 代码块、表和其他结构化内容的特殊处理
• 可通过模型上下文协议访问
• 通过禁用无头模式实时查看浏览器交互的选项
• 易于消费 npx 包裹。

NPX快速入门

建议使用此服务器的方式是通过 npx，这确保您运行的是最新版本，而无需克隆或手动安装。

1. 先决条件： 确保你已经安装了Node.js和npm。

1. 环境设置：

服务器需要 OPENAI_API_KEY。您可以通过两种方式提供此配置和其他可选配置：

- .env 文件： 创建一个 .env 您将运行的目录中的文件 npx 命令。 - Shell环境变量： 导出终端会话中的变量。

示例 .env 文件或shell导出：

   # Required
   OPENAI_API_KEY=your_api_key_here

   # Optional (defaults shown)
   # VISION_MODEL=gpt-4.1
   # API_BASE_URL=https://api.openai.com/v1   # Uncomment to override
   # TRANSPORT_TYPE=stdio                     # Options: stdio, sse, http
   # USE_SSE=true                             # Deprecated: use TRANSPORT_TYPE=sse instead
   # PORT=3001                                # Only used in sse/http modes
   # DISABLE_HEADLESS=true                    # Uncomment to see the browser in action

1. 运行服务器：

打开终端并运行：

   npx -y puppeteer-vision-mcp-server

- 这 -y 标志会自动确认来自的任何提示 npx. - 此命令将下载（如果尚未缓存）并执行服务器。 - 默认情况下，它从开始 stdio 模式。集 TRANSPORT_TYPE=sse 或 TRANSPORT_TYPE=http 对于HTTP服务器模式。

使用NPX作为MCP工具

该服务器被设计为集成在MCP兼容的LLM编排器中的工具。以下是一个示例配置片段：

{
  "mcpServers": {
    "web-scraper": {
      "command": "npx",
      "args": ["-y", "puppeteer-vision-mcp-server"],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE",
        // Optional:
        // "VISION_MODEL": "gpt-4.1",
        // "API_BASE_URL": "https://api.example.com/v1",
        // "TRANSPORT_TYPE": "stdio", // or "sse" or "http"
        // "DISABLE_HEADLESS": "true" // To see the browser during operations
      }
    }
    // ... other MCP servers
  }
}

当以这种方式配置时，MCP编排器将管理 puppeteer-vision-mcp-server 过程。

环境配置详细信息

无论您如何运行服务器（NPX或本地开发），它都会使用以下环境变量：

• OPENAI_API_KEY：（必需）用于访问视觉模型的API密钥。
• VISION_MODEL：（可选）用于视觉分析的模型。

- 违约： gpt-4.1 - 可以是任何具有视觉能力的模型。

• API_BASE_URL：（可选）自定义API终结点URL。

- 使用此选项连接到其他兼容OpenAI的提供商（例如Together.ai、Groq、Anthropic、本地部署）。

• TRANSPORT_TYPE：（可选）要使用的传输协议。

- 选项： stdio （默认）， sse, http - stdio：直接过程通信（建议用于大多数用例） - sse：服务器通过HTTP发送事件（传统模式） - http：具有会话管理的可流化HTTP传输

• USE_SSE：（可选，已弃用）设置为 true 通过HTTP启用SSE模式。

- 弃用：使用 TRANSPORT_TYPE=sse 相反。

• PORT：（可选）SSE或HTTP模式下HTTP服务器的端口。

- 违约： 3001.

• DISABLE_HEADLESS：（可选）设置为 true 以可见模式运行浏览器。

- 违约： false （浏览器以无头模式运行）。

通信模式

服务器支持三种通信模式：

1. stdio（默认）：通过标准输入/输出进行通信。

- 非常适合与管理流程的LLM工具直接集成。 - 非常适合命令行使用和脚本编写。 - 没有启动HTTP服务器。这是默认模式。

1. SSE模式：通过HTTP上的服务器发送事件进行通信。

- 通过设置启用 TRANSPORT_TYPE=sse 在您的环境中。 - 在指定的服务器上启动HTTP服务器 PORT （默认值：3001）。 - 当您需要通过网络连接到该工具时使用。 - 连接到： http://localhost:3001/sse

1. HTTP模式：通过Streamable HTTP传输与会话管理进行通信。

- 通过设置启用 TRANSPORT_TYPE=http 在您的环境中。 - 在指定的服务器上启动HTTP服务器 PORT （默认值：3001）。 - 支持完整的会话管理和可恢复的连接。 - 连接到： http://localhost:3001/mcp

工具使用（MCP调用）

服务器提供 scrape-webpage 工具。

刀具参数：

• url （string，必填）：要抓取的网页的URL。
• autoInteract （boolean，可选，默认值：true）：是否自动处理交互元素。
• maxInteractionAttempts （number，可选，默认值：3）：AI交互尝试的最大次数。
• waitForNetworkIdle （boolean，可选，默认值：true）：是否等待网络空闲后再进行处理。

响应格式：

该工具以结构化格式返回结果：

• content：一个数组，包含一个带有抓取网页原始标记的文本对象。
• metadata：包含其他信息：

- message：状态消息。 - success：表示成功的布尔值。 - contentSize：内容的大小（以字符为单位）（成功时）。

*成功响应示例：*

{
  "content": [
    {
      "type": "text",
      "text": "# Page Title\n\nThis is the content..."
    }
  ],
  "metadata": {
    "message": "Scraping successful",
    "success": true,
    "contentSize": 8734
  }
}

*错误响应示例：*

{
  "content": [
    {
      "type": "text",
      "text": ""
    }
  ],
  "metadata": {
    "message": "Error scraping webpage: Failed to load the URL",
    "success": false
  }
}

运作原理

AI驱动的交互

该系统使用具有视觉功能的AI模型（可通过以下方式配置 VISION_MODEL 和 API_BASE_URL)分析网页截图，并决定点击、打字或滚动等操作，以绕过叠加和同意书。此过程重复到 maxInteractionAttempts.

内容提取

交互后，Mozilla的可读性提取主要内容，然后使用Turndown对其进行净化并转换为Markdown，并为代码块和表制定自定义规则。

安装和开发（用于修改代码）

如果您想贡献、修改服务器或运行本地开发版本：

1. 克隆存储库：

   git clone https://github.com/djannot/puppeteer-vision-mcp.git
   cd puppeteer-vision-mcp

1. 安装依赖关系：

   npm install

1. 构建项目：

   npm run build

1. 设置环境：

创建一个 .env 项目根目录中的文件 OPENAI_API_KEY 以及任何其他所需的配置（见上文“环境配置详细信息”）。

1. 为发展而奔跑：

   npm start # Starts the server using the local build

或者，对于更改后的自动重建：

   npm run dev

定制（针对开发人员）

您可以通过编辑来修改刮刀的行为：

• src/ai/vision-analyzer.ts (analyzePageWithAI 功能）：自定义AI提示。
• src/ai/page-interactions.ts (executeAction 函数）：添加新的动作类型。
• src/scrapers/webpage-scraper.ts (visitWebPage 功能）：更改木偶选项。
• src/utils/markdown-formatters.ts：调整Markdown转换的调低规则。

依赖项

关键依赖关系包括：

• @modelcontextprotocol/sdk
• puppeteer, puppeteer-extra
• @mozilla/readability, jsdom
• turndown, sanitize-html
• openai （或用于视觉模型的兼容API）
• express （用于SSE模式）
• zod