内容
# puppeteer-mcp-server
一款 [MCP](https://modelcontextprotocol.io) 服务器，通过 [Puppeteer](https://pptr.dev/) 打开网页并根据 AI 客户端的指令执行浏览器操作。AI 通过快照检查页面，然后调用以下工具进行导航、点击、输入和读取结果。
## 要求
- Node.js 18+
- Chromium 由 Puppeteer 在 `npm install` 时自动下载。
## 安装
```bash
npm install
```
## 运行
```bash
npm start
```
服务器通过 **stdio** 使用 MCP 协议，因此通常由 MCP 客户端启动，而不是手动运行。
## 添加到 MCP 客户端
将客户端指向服务器命令。对于类似 Claude Desktop 的配置（`mcpServers` 块）：
```json
{
"mcpServers": {
"puppeteer": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/src/index.js"]
}
}
}
```
## 工具
| 工具 | 用途 |
| --- | --- |
| `browser_navigate` | 打开一个 URL。返回最终 URL、HTTP 状态和标题。 |
| `browser_snapshot` | 返回页面 URL、标题、可见文本和交互式元素的编号列表。每个元素都获得一个 `ref`。 |
| `browser_get_text` | 获取页面或通过 CSS 选择的某个元素的可见文本。 |
| `browser_click` | 通过 `ref`（来自快照）或 CSS `selector` 点击元素。 |
| `browser_type` | 通过 `ref` 或 `selector` 清除并输入到输入框/文本区域中，可选地按 Enter。 |
| `browser_press_key` | 按下单个按键（`Enter`、`Escape`、`ArrowDown` 等）。 |
| `browser_wait_for` | 等待 CSS `selector` 或某段 `text` 出现。 |
| `browser_evaluate` | 在页面中评估 JavaScript 表达式并返回结果。 |
| `browser_screenshot` | 返回页面的 PNG 快照（视口或完整页面）。 |
| `browser_go_back` | 在历史记录中导航回上一页。 |
| `browser_close` | 关闭浏览器并释放资源。 |
### 典型流程
1. `browser_navigate` 到一个 URL。
2. `browser_snapshot` 查看页面文本和可操作元素（每个元素都有一个 `ref`）。
3. 使用这些 `ref` 调用 `browser_click` / `browser_type`。
4. 再次调用 `browser_snapshot` 或 `browser_get_text` 读取结果。
由于单个浏览器实例在调用之间重复使用，因此 cookie 和导航状态在整个会话中持续，直到 `browser_close`。
## 配置
通过环境变量设置：
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `MCP_BROWSER_HEADLESS` | `true` | 设置为 `false` 以查看浏览器（用于调试）。 |
| `MCP_BROWSER_TIMEOUT_MS` | `30000` | 默认导航/等待超时。 |
| `MCP_BROWSER_WIDTH` | `1280` | 视口宽度。 |
| `MCP_BROWSER_HEIGHT` | `800` | 视口高度。 |
## 安全注意
`browser_evaluate` 在页面上下文中运行任意 JavaScript，服务器将导航到给定的任意 URL。请仅与受信任的客户端和指令一起运行。
## 许可证
MIT
