chrome-devtools-mcp-automation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chrome DevTools MCP Automation

Chrome DevTools MCP 自动化

Skill by ara.so — MCP Skills collection.

Chrome DevTools MCP (

chrome-devtools-mcp

) is a Model Context Protocol (MCP) server that gives AI coding agents full access to Chrome DevTools. It enables reliable browser automation via Puppeteer, advanced debugging (network inspection, console messages, screenshots), and performance analysis (trace recording, CrUX data).

由ara.so提供的Skill —— MCP Skills合集。

Chrome DevTools MCP（

chrome-devtools-mcp

）是一款Model Context Protocol（MCP）服务器，可为AI编码Agent提供Chrome DevTools的完整访问权限。它通过Puppeteer实现可靠的浏览器自动化、高级调试（网络检查、控制台消息、截图）以及性能分析（跟踪记录、CrUX数据）。

Installation

安装

As MCP Server (Standard Mode)

作为MCP服务器（标准模式）

Add to your MCP client configuration (e.g., Cursor, Claude Code, Cline, VS Code):

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

With options:

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--headless",
        "--no-usage-statistics",
        "--no-performance-crux"
      ]
    }
  }
}

添加到你的MCP客户端配置中（例如Cursor、Claude Code、Cline、VS Code）：

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

带选项配置：

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--headless",
        "--no-usage-statistics",
        "--no-performance-crux"
      ]
    }
  }
}

Slim Mode (Basic Browser Tasks Only)

精简模式（仅基础浏览器任务）

For simpler automation without performance tools:

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--slim", "--headless"]
    }
  }
}

针对无需性能工具的简单自动化场景：

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--slim", "--headless"]
    }
  }
}

Connect to Existing Browser

连接到已运行的浏览器

To connect to an already-running Chrome instance (useful for tools like Antigravity):

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  }
}

连接到已启动的Chrome实例（适用于Antigravity等工具）：

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--browser-url=http://127.0.0.1:9222"
      ]
    }
  }
}

CLI Usage (Without MCP)

CLI使用（无需MCP）

bash

undefined

bash

undefined

Install globally

全局安装

npm install -g chrome-devtools-mcp

Run CLI commands

运行CLI命令

chrome-devtools-mcp navigate --url https://example.com chrome-devtools-mcp screenshot --output screenshot.png chrome-devtools-mcp console-logs

undefined

chrome-devtools-mcp navigate --url https://example.com chrome-devtools-mcp screenshot --output screenshot.png chrome-devtools-mcp console-logs

undefined

Key Configuration Options

关键配置选项

Flag	Description
`--headless`	Run Chrome in headless mode (no UI)
`--slim`	Enable slim mode (basic tools only)
`--no-usage-statistics`	Opt out of Google usage statistics collection
`--no-performance-crux`	Disable Chrome UX Report (CrUX) API calls
`--browser-url=URL`	Connect to existing Chrome instance at URL
`--user-data-dir=PATH`	Use custom Chrome profile directory

标识	描述
`--headless`	以无头模式运行Chrome（无用户界面）
`--slim`	启用精简模式（仅基础工具）
`--no-usage-statistics`	选择退出Google使用统计数据收集
`--no-performance-crux`	禁用Chrome用户体验报告（CrUX）API调用
`--browser-url=URL`	连接到指定URL的已运行Chrome实例
`--user-data-dir=PATH`	使用自定义Chrome配置文件目录

Environment Variables

环境变量

bash

undefined

bash

undefined

Disable usage statistics

禁用使用统计数据

export CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1

Disable update checks

禁用更新检查

export CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS=1

Use in CI environment (auto-disables statistics)

在CI环境中使用（自动禁用统计数据）

export CI=true

undefined

export CI=true

undefined

Core Capabilities

核心功能

1. Browser Navigation & Interaction

1. 浏览器导航与交互

Navigate to a URL:

typescript

// MCP tool call: navigate
{
  "url": "https://example.com",
  "waitUntil": "networkidle0"
}

Click elements:

typescript

// MCP tool call: click
{
  "selector": "button.submit",
  "waitForNavigation": true
}

Fill forms:

typescript

// MCP tool call: type
{
  "selector": "input[name='email']",
  "text": "user@example.com",
  "delay": 100
}

Extract page content:

typescript

// MCP tool call: evaluate
{
  "script": "document.querySelector('h1').textContent",
  "returnByValue": true
}

导航至URL：

typescript

// MCP工具调用：navigate
{
  "url": "https://example.com",
  "waitUntil": "networkidle0"
}

点击元素：

typescript

// MCP工具调用：click
{
  "selector": "button.submit",
  "waitForNavigation": true
}

填写表单：

typescript

// MCP工具调用：type
{
  "selector": "input[name='email']",
  "text": "user@example.com",
  "delay": 100
}

提取页面内容：

typescript

// MCP工具调用：evaluate
{
  "script": "document.querySelector('h1').textContent",
  "returnByValue": true
}

2. Screenshots & Visual Inspection

2. 截图与视觉检查

Full page screenshot:

typescript

// MCP tool call: screenshot
{
  "fullPage": true,
  "path": "./screenshots/page.png"
}

Element screenshot:

typescript

// MCP tool call: screenshot
{
  "selector": "div.product-card",
  "path": "./element.png"
}

整页截图：

typescript

// MCP工具调用：screenshot
{
  "fullPage": true,
  "path": "./screenshots/page.png"
}

元素截图：

typescript

// MCP工具调用：screenshot
{
  "selector": "div.product-card",
  "path": "./element.png"
}

3. Network Inspection

3. 网络检查

Monitor network requests:

typescript

// MCP tool call: network-logs
{
  "filter": {
    "type": "fetch",
    "status": 200
  }
}

Analyze failed requests:

typescript

// MCP tool call: network-logs
{
  "filter": {
    "failed": true
  }
}

监控网络请求：

typescript

// MCP工具调用：network-logs
{
  "filter": {
    "type": "fetch",
    "status": 200
  }
}

分析失败请求：

typescript

// MCP工具调用：network-logs
{
  "filter": {
    "failed": true
  }
}

4. Console & Debugging

4. 控制台与调试

Get console messages:

typescript

// MCP tool call: console-logs
{
  "level": "error"  // or "warning", "info", "log"
}

Execute JavaScript in page context:

typescript

// MCP tool call: evaluate
{
  "script": `
    const errors = [];
    window.addEventListener('error', (e) => {
      errors.push({ message: e.message, stack: e.error.stack });
    });
    errors;
  `,
  "returnByValue": true
}

获取控制台消息：

typescript

// MCP工具调用：console-logs
{
  "level": "error"  // 或 "warning", "info", "log"
}

在页面上下文执行JavaScript：

typescript

// MCP工具调用：evaluate
{
  "script": `
    const errors = [];
    window.addEventListener('error', (e) => {
      errors.push({ message: e.message, stack: e.error.stack });
    });
    errors;
  `,
  "returnByValue": true
}

5. Performance Analysis

5. 性能分析

Record performance trace:

typescript

// MCP tool call: start-trace
{
  "categories": ["devtools.timeline", "v8.execute", "disabled-by-default-v8.cpu_profiler"]
}

// ... perform actions ...

// MCP tool call: stop-trace
{
  "path": "./traces/performance.json"
}

Get performance metrics:

typescript

// MCP tool call: get-metrics
{
  "includeMemory": true
}

Analyze Core Web Vitals:

typescript

// MCP tool call: web-vitals
{
  "url": "https://example.com",
  "includeCrux": true  // Include real-user data from CrUX
}

记录性能跟踪：

typescript

// MCP工具调用：start-trace
{
  "categories": ["devtools.timeline", "v8.execute", "disabled-by-default-v8.cpu_profiler"]
}

// ... 执行操作 ...

// MCP工具调用：stop-trace
{
  "path": "./traces/performance.json"
}

获取性能指标：

typescript

// MCP工具调用：get-metrics
{
  "includeMemory": true
}

分析核心Web指标：

typescript

// MCP工具调用：web-vitals
{
  "url": "https://example.com",
  "includeCrux": true  // 包含来自CrUX的真实用户数据
}

Common Patterns

常见模式

Pattern 1: E2E Test Automation

模式1：端到端（E2E）测试自动化

typescript

// 1. Navigate to login page
// Tool: navigate
{ "url": "https://app.example.com/login" }

// 2. Fill credentials
// Tool: type
{ "selector": "#username", "text": "testuser" }
{ "selector": "#password", "text": "secure_password" }

// 3. Submit form
// Tool: click
{ "selector": "button[type='submit']", "waitForNavigation": true }

// 4. Verify success
// Tool: evaluate
{ "script": "window.location.pathname === '/dashboard'" }

// 5. Capture proof
// Tool: screenshot
{ "path": "./test-evidence/login-success.png" }

typescript

// 1. 导航至登录页面
// 工具：navigate
{ "url": "https://app.example.com/login" }

// 2. 填写凭证
// 工具：type
{ "selector": "#username", "text": "testuser" }
{ "selector": "#password", "text": "secure_password" }

// 3. 提交表单
// 工具：click
{ "selector": "button[type='submit']", "waitForNavigation": true }

// 4. 验证成功
// 工具：evaluate
{ "script": "window.location.pathname === '/dashboard'" }

// 5. 捕获验证证据
// 工具：screenshot
{ "path": "./test-evidence/login-success.png" }

Pattern 2: Performance Audit

模式2：性能审计

typescript

// 1. Start trace recording
// Tool: start-trace
{ "categories": ["devtools.timeline", "loading", "blink.user_timing"] }

// 2. Navigate to page
// Tool: navigate
{ "url": "https://example.com/product/123", "waitUntil": "networkidle0" }

// 3. Stop trace
// Tool: stop-trace
{ "path": "./audits/product-page-trace.json" }

// 4. Get Core Web Vitals
// Tool: web-vitals
{ "url": "https://example.com/product/123", "includeCrux": true }

// 5. Analyze metrics
// Tool: get-metrics
{ "includeMemory": true }

typescript

// 1. 启动跟踪记录
// 工具：start-trace
{ "categories": ["devtools.timeline", "loading", "blink.user_timing"] }

// 2. 导航至页面
// 工具：navigate
{ "url": "https://example.com/product/123", "waitUntil": "networkidle0" }

// 3. 停止跟踪
// 工具：stop-trace
{ "path": "./audits/product-page-trace.json" }

// 4. 获取核心Web指标
// 工具：web-vitals
{ "url": "https://example.com/product/123", "includeCrux": true }

// 5. 分析指标
// 工具：get-metrics
{ "includeMemory": true }

Pattern 3: Debugging Production Issues

模式3：生产问题调试

typescript

// 1. Navigate to problematic page
// Tool: navigate
{ "url": "https://example.com/checkout" }

// 2. Monitor network for failed requests
// Tool: network-logs
{ "filter": { "failed": true } }

// 3. Capture console errors
// Tool: console-logs
{ "level": "error" }

// 4. Get JavaScript errors with stack traces
// Tool: evaluate
{
  "script": `
    window.__errors = [];
    window.addEventListener('error', (e) => {
      __errors.push({
        message: e.message,
        filename: e.filename,
        lineno: e.lineno,
        colno: e.colno,
        stack: e.error?.stack
      });
    });
    setTimeout(() => __errors, 5000);
  `,
  "returnByValue": true
}

// 5. Screenshot for visual context
// Tool: screenshot
{ "fullPage": true, "path": "./debug/error-state.png" }

typescript

// 1. 导航至问题页面
// 工具：navigate
{ "url": "https://example.com/checkout" }

// 2. 监控网络中的失败请求
// 工具：network-logs
{ "filter": { "failed": true } }

// 3. 捕获控制台错误
// 工具：console-logs
{ "level": "error" }

// 4. 获取带堆栈跟踪的JavaScript错误
// 工具：evaluate
{
  "script": `
    window.__errors = [];
    window.addEventListener('error', (e) => {
      __errors.push({
        message: e.message,
        filename: e.filename,
        lineno: e.lineno,
        colno: e.colno,
        stack: e.error?.stack
      });
    });
    setTimeout(() => __errors, 5000);
  `,
  "returnByValue": true
}

// 5. 截图获取视觉上下文
// 工具：screenshot
{ "fullPage": true, "path": "./debug/error-state.png" }

Pattern 4: Data Extraction (Web Scraping)

模式4：数据提取（网页抓取）

typescript

// 1. Navigate to target page
// Tool: navigate
{ "url": "https://example.com/products" }

// 2. Wait for dynamic content
// Tool: wait-for-selector
{ "selector": "div.product-list", "timeout": 5000 }

// 3. Extract structured data
// Tool: evaluate
{
  "script": `
    Array.from(document.querySelectorAll('.product-card')).map(card => ({
      title: card.querySelector('h3').textContent.trim(),
      price: card.querySelector('.price').textContent.trim(),
      url: card.querySelector('a').href,
      inStock: !card.querySelector('.out-of-stock')
    }))
  `,
  "returnByValue": true
}

// 4. Handle pagination
// Tool: click
{ "selector": "button.next-page", "waitForNavigation": true }

typescript

// 1. 导航至目标页面
// 工具：navigate
{ "url": "https://example.com/products" }

// 2. 等待动态内容加载
// 工具：wait-for-selector
{ "selector": "div.product-list", "timeout": 5000 }

// 3. 提取结构化数据
// 工具：evaluate
{
  "script": `
    Array.from(document.querySelectorAll('.product-card')).map(card => ({
      title: card.querySelector('h3').textContent.trim(),
      price: card.querySelector('.price').textContent.trim(),
      url: card.querySelector('a').href,
      inStock: !card.querySelector('.out-of-stock')
    }))
  `,
  "returnByValue": true
}

// 4. 处理分页
// 工具：click
{ "selector": "button.next-page", "waitForNavigation": true }

Pattern 5: Visual Regression Testing

模式5：视觉回归测试

typescript

// 1. Set consistent viewport
// Tool: set-viewport
{ "width": 1280, "height": 720, "deviceScaleFactor": 1 }

// 2. Navigate to page
// Tool: navigate
{ "url": "https://example.com/landing" }

// 3. Wait for animations to complete
// Tool: wait-for-timeout
{ "timeout": 2000 }

// 4. Take baseline screenshot
// Tool: screenshot
{
  "fullPage": true,
  "path": "./visual-tests/baseline.png"
}

// 5. Compare against previous baseline (in your test framework)
// Tool: screenshot
{
  "fullPage": true,
  "path": "./visual-tests/current.png"
}

typescript

// 1. 设置一致的视口
// 工具：set-viewport
{ "width": 1280, "height": 720, "deviceScaleFactor": 1 }

// 2. 导航至页面
// 工具：navigate
{ "url": "https://example.com/landing" }

// 3. 等待动画完成
// 工具：wait-for-timeout
{ "timeout": 2000 }

// 4. 拍摄基准截图
// 工具：screenshot
{
  "fullPage": true,
  "path": "./visual-tests/baseline.png"
}

// 5. 与之前的基准截图对比（在你的测试框架中）
// 工具：screenshot
{
  "fullPage": true,
  "path": "./visual-tests/current.png"
}

Troubleshooting

故障排查

Browser Won't Start

浏览器无法启动

Issue: MCP server fails with "Browser not found"

Solution:

bash

undefined

问题： MCP服务器启动失败，提示“Browser not found”

解决方案：

bash

undefined

Specify Chrome executable path

指定Chrome可执行文件路径

export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Or use Chrome for Testing

或使用Chrome for Testing

npx @puppeteer/browsers install chrome@stable

undefined

npx @puppeteer/browsers install chrome@stable

undefined

Port Already in Use

端口已被占用

Issue: "Port 9222 already in use"

Solution:

bash

undefined

问题： “Port 9222 already in use”

解决方案：

bash

undefined

Find and kill existing Chrome instance

查找并终止已运行的Chrome实例

lsof -ti:9222 | xargs kill -9

Or use custom port

或使用自定义端口

In MCP config, add: "--remote-debugging-port=9223"

在MCP配置中添加："--remote-debugging-port=9223"

undefined

undefined

Timeout Errors

超时错误

Issue: "Navigation timeout of 30000 ms exceeded"

Solution:

typescript

// Increase timeout for slow pages
// Tool: navigate
{
  "url": "https://slow-site.com",
  "timeout": 60000,
  "waitUntil": "domcontentloaded"  // Less strict than "networkidle0"
}

问题： “Navigation timeout of 30000 ms exceeded”

解决方案：

typescript

// 为加载缓慢的页面增加超时时间
// 工具：navigate
{
  "url": "https://slow-site.com",
  "timeout": 60000,
  "waitUntil": "domcontentloaded"  // 比"networkidle0"要求更低
}

Headless Mode Issues

无头模式问题

Issue: Site behaves differently in headless mode

Solution:

json

// Remove --headless flag temporarily to debug
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

问题： 网站在无头模式下表现异常

解决方案：

json

// 临时移除--headless标识以调试
{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}

Memory Leaks in Long-Running Sessions

长时间会话中的内存泄漏

Issue: Chrome consumes excessive memory over time

Solution:

typescript

// Close and reopen browser periodically
// Tool: close-browser
{}

// Browser will auto-restart on next tool call

问题： Chrome随时间推移占用过多内存

解决方案：

typescript

// 定期关闭并重新打开浏览器
// 工具：close-browser
{}

// 下次工具调用时浏览器将自动重启

Source Map Errors

源映射错误

Issue: Stack traces not showing original source

Solution:

bash

undefined

问题： 堆栈跟踪未显示原始源代码

解决方案：

bash

// 确保源映射与应用一起部署
// 在网络标签中检查.map文件请求
// 工具：network-logs
{ "filter": { "type": "other" } }

Ensure source maps are deployed with your app

企业代理/防火墙

Check Network tab for .map file requests

—

Tool: network-logs

—

{ "filter": { "type": "other" } }

undefined

问题： 无法下载Chrome或连接到CrUX API

解决方案：

bash

undefined

Corporate Proxy/Firewall

设置代理环境变量

Issue: Cannot download Chrome or connect to CrUX API

Solution:

bash

undefined

export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080

Set proxy environment variables

如果API调用失败，禁用CrUX

—

添加标识：--no-performance-crux

export HTTP_PROXY=http://proxy.company.com:8080 export HTTPS_PROXY=http://proxy.company.com:8080

undefined

Disable CrUX if API calls fail

要求

Add flag: --no-performance-crux

—

undefined

Node.js： v20.19或更新版本（最新维护LTS版本）
Chrome： 当前稳定版或更新版本
npm： 任何最新版本
操作系统： macOS、Linux或Windows 11+

Requirements

隐私与数据收集

Node.js: v20.19 or newer (latest maintenance LTS)
Chrome: Current stable version or newer
npm: Any recent version
OS: macOS, Linux, or Windows 11+

使用统计数据： 默认启用。可通过
```
--no-usage-statistics
```
标识或
```
CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1
```
环境变量选择退出。
CrUX API： 性能工具可能会将跟踪URL发送至Google CrUX API。可通过
```
--no-performance-crux
```
禁用。
浏览器数据： 所有浏览器内容都会暴露给MCP客户端。请勿用于你不愿共享的敏感/个人数据。

Privacy & Data Collection

最佳实践

Usage Statistics: Enabled by default. Opt out with
```
--no-usage-statistics
```
flag or
```
CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS=1
```
env var.
CrUX API: Performance tools may send trace URLs to Google CrUX API. Disable with
```
--no-performance-crux
```
.
Browser Data: All browser content is exposed to MCP clients. Do not use with sensitive/personal data you don't want to share.

简单任务使用精简模式： 如果你只需要导航和截图功能，使用
```
--slim
```
标识以减少启动时间。
CI环境默认使用无头模式： 在自动化环境中始终使用
```
--headless
```
。
合理设置超时时间： 根据预期页面加载时间调整导航超时时间。
清理资源： 对于长时间运行的脚本，定期关闭浏览器以释放内存。
生产环境固定版本： 使用
```
chrome-devtools-mcp@X.Y.Z
```
而非
```
@latest
```
以确保构建可复现。
监控网络： 在假设页面加载问题与浏览器相关之前，先检查
```
network-logs
```
。
利用源映射： 在预发布/测试环境中部署源映射以获得更好的调试体验。

Best Practices

额外资源

Use Slim Mode for Simple Tasks: If you only need navigation and screenshots, use
```
--slim
```
to reduce startup time.
Headless by Default in CI: Always use
```
--headless
```
in automated environments.
Set Timeouts Appropriately: Adjust navigation timeouts based on expected page load times.
Clean Up Resources: For long-running scripts, periodically close the browser to free memory.
Version Pin in Production: Use
```
chrome-devtools-mcp@X.Y.Z
```
instead of
```
@latest
```
for reproducible builds.
Monitor Network: Check
```
network-logs
```
before assuming page load issues are browser-related.
Leverage Source Maps: Deploy source maps in staging/test environments for better debugging.

工具参考： 标准 | 精简
CLI文档： CLI指南
故障排查： 完整指南
Puppeteer API： 官方文档
Chrome DevTools协议： 协议参考

Additional Resources

—

Tool Reference: Standard | Slim
CLI Documentation: CLI Guide
Troubleshooting: Full Guide
Puppeteer API: Official Docs
Chrome DevTools Protocol: Protocol Reference

—