pptr MCP

pptr mcp

通过Puppeteer实现浏览器自动化的MCP服务器。与其他公开固定工具（导航、单击、截图）的浏览器MCP不同，此服务器执行任意JavaScript代码，可以直接访问Puppeteer browser实例。

主要区别

大多数浏览器MCP服务器提供一组有限的预定义操作。对于复杂的工作流程，这种方法需要多次往返，无法处理边缘情况。

pptr mcp 采用不同的方法：它公开了一个 execute 在Node.js虚拟机中运行JavaScript代码的工具 browser 全球的。您直接编写Puppeteer代码，在一次调用中获得完整的API访问权限。

Traditional MCP (5 round-trips)         pptr-mcp (1 round-trip)
================================        ================================

  Agent           Server                  Agent           Server
    |                |                      |                |
    |-- navigate --->|                      |-- execute ---->|
    ||                      |   | const page = await     |
    ||                      |   | await page.click(s);   |
    ||                      |   |   page.screenshot();   |
    ||                      |=20

## 安装

npm install -g pptr-mcp

## MCP配置

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{ "mcpServers": { "puppeteer": { "command": "npx", "args": ["pptr-mcp"] } } }

使用CLI选项：

{ "mcpServers": { "puppeteer": { "command": "npx", "args": ["pptr-mcp", "--no-headless", "--viewport=1080p"] } } }

带有自定义Chrome标志（之后 `--`):

{ "mcpServers": { "puppeteer": { "command": "npx", "args": [ "pptr-mcp", "--viewport=1280x720", "--", "--proxy-server=http://proxy:8080" ] } } }

## CLI选项

|选项|描述|
| ------------------ | -------------------------------------------- |
| `--no-headless` |使用可见的浏览器窗口运行|
| `--viewport=VALUE` |设置视口大小（例如1920x1080或1080p）|
| `--help, -h` |显示帮助|
| `-- [args]` |将剩余参数传递给Chrome|

之前未知的选项 `--` 也传递给Chrome。

## Claude代码插件

安装为Claude Code插件：

/plugin marketplace add iatsiuk/pptr-mcp /plugin install pptr-mcp@pptr-mcp

## 环境变量

|变量|描述|
| --------------------------- | ---------------------------------------- |
| `CHROME_PATH` |Chrome可执行文件的路径|
| `PUPPETEER_EXECUTABLE_PATH` |CHROME_PATH的替代方案|
| `PUPPETEER_CACHE_DIR` |浏览器下载缓存目录|
| `PPTR_MCP_TIMEOUT` |执行超时（毫秒）（默认值：30000）|

## 工具：执行

通过访问Puppeteer浏览器执行JavaScript代码。

### 参数

|名称|类型|默认值|描述|
| ------------ | ------- | -------- | ---------------------------------- |
| `code` |string |必需|要执行的JavaScript代码|
| `persistent` |boolean | true |跨调用重用浏览器会话|

## 食谱

### 禁用无头模式

执行期间显示浏览器窗口：

{ "mcpServers": { "puppeteer": { "command": "npx", "args": ["pptr-mcp", "--no-headless"] } } }

### 自定义Chrome配置文件目录

使用您自己的Chrome个人资料，保存登录信息和Cookie：

{ "mcpServers": { "puppeteer": { "command": "npx", "args": ["pptr-mcp", "--", "--user-data-dir=/path/to/profile"] } } }

### 使用系统Chrome而不是下载

默认情况下，pptr-mcp会下载Chrome for Testing，这是一个针对捆绑的Puppeteer进行优化和测试的版本。要使用您的系统Chrome，请执行以下操作：

{ "mcpServers": { "puppeteer": { "command": "npx", "args": ["pptr-mcp"], "env": { "CHROME_PATH": "/path/to/chrome" } } } }

## 安全

此服务器设计用于 **值得信赖的地方发展** 与法学硕士助理（Claude Code、Cursor等）合作。根据您的请求，执行代码来自LLM。

### 这意味着什么

- **不是沙盒**：Node.js VM隔离代码是为了方便，而不是为了安全。它不是为运行不受信任的代码而设计的。
- **完全浏览器控制**：执行的代码可以导航到任何URL，读取页面内容，截图，并与web应用程序交互。
- **Chrome在没有沙箱的情况下运行**: `--no-sandbox` 标志用于Docker/容器兼容性。
- **持续会话**：与 `persistent: true` （默认），Cookie和浏览器状态在调用过程中会被保留。使用 `persistent: false` 为了隔离。

### 不是为

- 多租户或共享服务器部署
- 执行来自外部源的不受信任的代码
- 构建接受任意用户输入的web服务

## 许可证

[WTFPL](LICENSE.md)