# browser-devtools-mcp

通过 Chrome DevTools Protocol (CDP) 读取浏览器 DevTools 数据的 MCP Server。

支持 Chrome、Edge 及所有 Chromium 内核浏览器。

## 功能

- 列出浏览器所有标签页
- 读取控制台报错/警告
- 列出网络请求
- 读取网络请求的响应体（大响应存临时文件，提供摘要）
- 页面截图
- 读取 DOM 结构
- 读取计算后的 CSS 样式
- 在页面上下文执行 JavaScript
- 清理临时响应文件

## 快速开始

### 1. 启动浏览器（带调试端口）

```bash
# Chrome
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Edge
/Applications/Microsoft\ Edge.app/Contents/MacOS/Microsoft\ Edge --remote-debugging-port=9222 --user-data-dir=/tmp/edge-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug
```

也可以使用项目自带的启动脚本（支持 Chrome 和 Edge）：

```bash
./launch-browser.sh chrome
./launch-browser.sh edge
```

### 2. 配置 MCP 客户端

在 kscc / Claude Code 的 `~/.claude/settings.json` 或项目 `.claude/settings.json` 中添加：

```json
{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "browser-devtools-mcp"],
      "env": {
        "CDP_PORT": "9222"
      }
    }
  }
}
```

全局安装后可直接用：

```json
{
  "mcpServers": {
    "browser-devtools": {
      "command": "browser-devtools-mcp",
      "env": {
        "CDP_PORT": "9222"
      }
    }
  }
}
```

### 3. 重启 MCP 客户端

## 配置项

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| `CDP_PORT` | `9222` | Chrome DevTools Protocol 调试端口 |

## 工具列表

| 工具 | 说明 |
|------|------|
| `list_tabs` | 列出所有浏览器标签页 |
| `get_console_errors` | 读取控制台错误/警告（2秒捕获窗口） |
| `get_network_requests` | 列出网络请求，支持按状态码、URL、Action 过滤 |
| `get_network_response` | 读取请求响应体；大响应保存到临时文件并返回摘要和文件路径 |
| `clean_temp_files` | 清理保存的临时响应文件 |
| `take_screenshot` | 截取当前页面或指定元素 |
| `get_dom_snapshot` | 读取指定选择器的 DOM 结构 |
| `get_computed_styles` | 读取元素计算后的 CSS 样式 |
| `execute_js` | 在页面上下文执行 JavaScript |

## Chrome 扩展（可选）

扩展在 `document_start` 阶段捕获控制台错误，用于捕获 CDP 连接前就发生的报错。不装也能用所有核心功能。

安装方式：

1. 打开 `chrome://extensions/`
2. 开启开发者模式
3. 点击"加载已解压的扩展程序"
4. 选择本项目的 `extension/` 目录

## 工作原理

所有数据**实时从浏览器读取**，不做任何缓存和存储：

- **CDP HTTP** 用于标签页列表（`/json`）
- **CDP WebSocket** 用于 Runtime 事件、Network 事件和命令调用
- **Performance API**（通过 `Runtime.evaluate`）用于获取 CDP 启动前的历史请求
- **临时文件** 仅用于大响应——按需保存，用 `clean_temp_files` 清理

## License

MIT