puppeteer-mcp-克劳德

Name: puppeteer-mcp-克劳德
Author: jaenster

作者：jaenster16 星标更新：2025-07-30

安装使用来源：spider==github.com

项目介绍

MCP Puppeteer Server

这是一个通过Puppeteer提供全面浏览器自动化能力的Model Context Protocol (MCP)服务器。此服务器允许Claude与网页交互，抓取屏幕截图，执行JavaScript，并完成各种浏览器自动化任务。

🚀 快速开始

想要在Claude Code中实现浏览器自动化？运行这个命令：

claude mcp add puppeteer-mcp-claude

替代方法 - 适用于Claude Desktop和Claude Code：

npx puppeteer-mcp-claude install

就这样！ 安装程序会自动：

检测系统上的Claude Desktop和Claude Code
配置两个应用程序以支持浏览器自动化工具
验证所有检测到的Claude应用是否正常工作

然后重启你的Claude应用并询问：“抓取google.com的屏幕截图”来测试一下！

🖥️ 跨平台支持

macOS: Claude Desktop + Claude Code
Linux: Claude Desktop + Claude Code
Windows: 仅限Claude Code

功能

浏览器管理: 启动和关闭Chrome/Chromium浏览器
页面操作: 创建、导航和管理多个浏览器标签页
元素交互: 点击、输入文本并从网页元素中提取文本
JavaScript执行: 在浏览器上下文中运行自定义JavaScript代码
屏幕截图捕获: 抓取全屏或视口截图
选择器等待: 等待元素出现，可配置超时时间
多页面支持: 同时管理多个浏览器标签页

可用工具

工具	描述
`puppeteer_launch`	启动一个新的浏览器实例
`puppeteer_new_page`	创建一个新的浏览器标签页
`puppeteer_navigate`	导航到一个URL
`puppeteer_click`	点击一个元素
`puppeteer_type`	在输入字段中输入文本
`puppeteer_get_text`	从元素中提取文本
`puppeteer_screenshot`	抓取屏幕截图
`puppeteer_evaluate`	执行JavaScript代码
`puppeteer_wait_for_selector`	等待一个元素出现
`putter_close_page`	关闭特定的标签页
`puppeteer_close_browser`	关闭整个浏览器

安装

🚀 自动设置（推荐）

只需一个命令即可在所有Claude应用中获得浏览器自动化功能：

npx puppeteer-mcp-claude install

自动处理以下步骤：

✅ 从npm下载最新版本
✅ 检测系统上的Claude Desktop和Claude Code
✅ 自动配置两个应用程序
✅ 如需创建配置文件（跨平台路径）
✅ 验证一切是否正常工作
✅ 显示下一步的具体操作

跨平台检测：

macOS: ~/Library/Application Support/Claude/ (Desktop) + ~/.claude/ (Code)
Linux: ~/.config/Claude/ (Desktop) + ~/.claude/ (Code)
Windows: ~/.claude/ (仅限Code)

安装后：

重启任何正在运行的Claude应用程序
询问Claude："列出所有可用工具"
你会看到11个新的Puppeteer工具用于浏览器自动化！

无需手动配置！ 安装程序会在所有平台上处理一切。

手动安装

如果你更喜欢手动安装：

全局安装包：
```
npm install -g puppeteer-mcp-claude
```
配置Claude Code：
```
puppeteer-mcp-claude install
```

开发安装

为了开发或贡献：

克隆并安装依赖项：

git clone https://github.com/jaenster/puppeteer-mcp-claude.git
cd puppeteer-m
npm install

构建项目：
```
npm run build
```
使用本地设置脚本：
```
npm run setup-mcp
```

管理命令

命令	描述
`npx puppeteer-mcp-claude install`	安装并配置Claude Desktop & Code
`npx puppeteer-mcp-claude uninstall`	从所有Claude应用中移除
`npx puppeteer-mcp-claude status`	检查所有应用中的安装状态
`npx puppeteer-mcp-claude help`	显示帮助和可用工具

替代安装方法

方法1：使用Claude Code MCP命令（推荐）

使用Claude Code内置的MCP管理进行配置：

claude mcp add puppeteer-mcp-claude

方法2：手动配置

编辑或创建 ~/.claude/claude_desktop_config.json：

{
  "mcpServers": {
    "puppeteer-mcp-claude": {
      "command": "npx",
      "args": ["puppeteer-mcp-claude", "serve"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

安装后步骤

如果Claude Code当前正在运行，请重启它
测试集成：
```
npm run test:integration
```
在Claude Code中验证，询问："列出所有可用工具"

你应该能看到Puppeteer工具列在可用工具中。

使用示例

基本Web自动化

// 启动浏览器
await puppeteer_launch({ headless: false });

// 创建一个新的页面
await puppeteer_new_page({ pageId: "main" });

// 导航到一个网站
await puppeteer_navigate({ 
  pageId: "main", 
  url: "https://example.com" 
});

// 抓取屏幕截图
await puppeteer_screenshot({ 
  pageId: "main", 
  path: "screenshot.png" 
});

表单交互

// 在搜索框中输入文本
await puppeteer_type({ 
  pageId: "main", 
  selector: "input[name='search']", 
  text: "Claude AI" 
});

// 点击按钮
await puppeteer_click({ 
  pageId: "main", 
  selector: "button[type='submit']" 
});

// 等待结果加载
await puppeteer_wait_for_selector({ 
  pageId: "main", 
  selector: ".search-results" 
});

数据提取

// 从元素中提取文本
await puppeteer_get_text({ 
  pageId: "main", 
  selector: "h1" 
});

// 执行自定义JavaScript
await puppeteer_evaluate({ 
  pageId: "main", 
  script: "document.querySelectorAll('a').length" 
});

配置选项

浏览器启动选项

headless: 在无头模式下运行浏览器（默认：true）
args: Chrome参数数组（例如，["--disable-web-security"]）

导航选项

waitUntil: 导航等待条件
- load: 等待加载事件
- domcontentloaded: 等待DOM内容加载
- networkidle0: 等待没有网络活动
- networkidle2: 等待最多2个网络连接

屏幕截图选项

path: 保存截图的文件路径
fullPage: 捕获完整的页面滚动高度（默认：false）

管理命令

命令	描述
`npm run setup-mcp`	自动配置MCP服务器
`npm run remove-mcp`	移除MCP服务器配置
`npm run status-mcp`	检查当前配置状态
`npm run test:integration`	测试MCP服务器集成

故障排除

常见问题

Claude Code看不到工具：
- 确保在配置后重启了Claude Code
- 检查claude_desktop_config.json中的路径是否正确
- 使用npm run status-mcp验证MCP服务器是否配置正确
“浏览器未启动”错误：
- 在使用其他工具之前始终调用puppeteer_launch
- 确保浏览器启动成功
元素未找到错误：
- 在与元素交互之前使用puppeteer_wait_for_selector
- 使用浏览器开发者工具验证选择器是否正确
权限错误：
- 确保项目目录具有正确的权限
- 检查ts-node是否已安装且可访问

调试模式

为了调试，你可以运行开发模式下的服务器：

npm run dev

这将显示所有MCP操作的详细日志。

测试

运行测试套件以验证一切是否正常：

npm test

对于与Claude Code的集成测试：

npm run test:integration

安全考虑

服务器以用户相同的权限运行
浏览器实例在退出时会被自动清理
所有JavaScript执行都在浏览器上下文中，而不是Node.js进程中
网络请求遵循与普通Chrome浏览器相同的网络安全策略

要求

Node.js 16或更高版本
Chrome/Chromium浏览器（由Puppeteer自动下载）
支持MCP的Claude Code
TypeScript支持（ts-node）

支持

如果你遇到问题：

查看上面的故障排除部分
使用npm run status-mcp验证配置
运行集成测试npm run test:integration
检查Claude Code的日志以查找与MCP相关的错误

如需更多帮助，请参阅Claude Code MCP文档。