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 — Devtools Skills collection.

Chrome DevTools MCP (

chrome-devtools-mcp

) is an MCP server that gives AI coding agents full control over Chrome browser automation, debugging, and performance analysis. It exposes Chrome DevTools Protocol and Puppeteer capabilities through MCP tools, enabling reliable browser automation, performance profiling, network inspection, and advanced debugging.

由ara.so开发的Skill — Devtools Skills工具集。

Chrome DevTools MCP（

chrome-devtools-mcp

）是一款MCP服务器，可为AI编码Agent提供对Chrome浏览器自动化、调试和性能分析的完全控制权限。它通过MCP工具开放Chrome DevTools Protocol和Puppeteer的功能，实现可靠的浏览器自动化、性能分析、网络检查及高级调试。

Installation

安装

MCP Client Configuration

MCP客户端配置

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

json

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

Slim mode (basic browser tasks only):

json

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

Disable usage statistics and update checks:

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"],
      "env": {
        "CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS": "1"
      }
    }
  }
}

将以下配置添加到你的MCP客户端配置中（例如Claude Desktop、Cursor、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", "--slim", "--headless"]
    }
  }
}

禁用使用统计和更新检查：

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest", "--no-usage-statistics"],
      "env": {
        "CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS": "1"
      }
    }
  }
}

CLI Usage (Without MCP)

无需MCP的CLI使用方式

bash

undefined

bash

undefined

Install globally

全局安装

npm install -g chrome-devtools-mcp

Run CLI

运行CLI

chrome-devtools-mcp --help

undefined

chrome-devtools-mcp --help

undefined

Requirements

系统要求

Node.js v20.19+ (latest maintenance LTS)
Chrome stable or newer
npm

Node.js v20.19+（最新维护版LTS）
Chrome稳定版或更高版本
npm

Key MCP Tools

核心MCP工具

Once the MCP server is running, your AI agent has access to these tools:

MCP服务器运行后，AI Agent即可使用以下工具：

Browser Control

浏览器控制

browser_navigate
- Navigate to a URL

typescript

// Navigate to a page
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://example.com"
});

browser_click
- Click an element

typescript

// Click by selector
await use_mcp_tool("chrome-devtools", "browser_click", {
  selector: "button.submit"
});

// Click with custom wait
await use_mcp_tool("chrome-devtools", "browser_click", {
  selector: "#login-btn",
  waitUntil: "networkidle2"
});

browser_type
- Type text into an input

typescript

// Type into a field
await use_mcp_tool("chrome-devtools", "browser_type", {
  selector: "input[name='email']",
  text: "user@example.com"
});

// Type with delay between keystrokes
await use_mcp_tool("chrome-devtools", "browser_type", {
  selector: "#search",
  text: "search query",
  delay: 100
});

browser_screenshot
- Capture screenshot

typescript

// Full page screenshot
await use_mcp_tool("chrome-devtools", "browser_screenshot", {
  fullPage: true
});

// Element screenshot
await use_mcp_tool("chrome-devtools", "browser_screenshot", {
  selector: ".main-content",
  fullPage: false
});

browser_evaluate
- Execute JavaScript in browser

typescript

// Get page data
await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: "document.title"
});

// Interact with page
await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: `
    const items = Array.from(document.querySelectorAll('.item'));
    return items.map(el => ({
      text: el.textContent,
      href: el.querySelector('a')?.href
    }));
  `
});

browser_navigate
- 导航至指定URL

typescript

// 导航到页面
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://example.com"
});

browser_click
- 点击元素

typescript

// 通过选择器点击
await use_mcp_tool("chrome-devtools", "browser_click", {
  selector: "button.submit"
});

// 自定义等待时间后点击
await use_mcp_tool("chrome-devtools", "browser_click", {
  selector: "#login-btn",
  waitUntil: "networkidle2"
});

browser_type
- 在输入框中输入文本

typescript

// 在输入框中输入内容
await use_mcp_tool("chrome-devtools", "browser_type", {
  selector: "input[name='email']",
  text: "user@example.com"
});

// 按键间隔延迟输入
await use_mcp_tool("chrome-devtools", "browser_type", {
  selector: "#search",
  text: "search query",
  delay: 100
});

browser_screenshot
- 捕获截图

typescript

// 整页截图
await use_mcp_tool("chrome-devtools", "browser_screenshot", {
  fullPage: true
});

// 元素截图
await use_mcp_tool("chrome-devtools", "browser_screenshot", {
  selector: ".main-content",
  fullPage: false
});

browser_evaluate
- 在浏览器中执行JavaScript

typescript

// 获取页面数据
await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: "document.title"
});

// 与页面交互
await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: `
    const items = Array.from(document.querySelectorAll('.item'));
    return items.map(el => ({
      text: el.textContent,
      href: el.querySelector('a')?.href
    }));
  `
});

Performance Analysis

性能分析

performance_record
- Record performance trace

typescript

// Record a page load
await use_mcp_tool("chrome-devtools", "performance_record", {
  url: "https://example.com",
  duration: 10000, // 10 seconds
  throttling: "4g" // Simulate 4G network
});

performance_analyze
- Analyze performance metrics

typescript

// Get performance insights
await use_mcp_tool("chrome-devtools", "performance_analyze", {
  traceUrl: "trace-data-url",
  includeFieldData: true // Include CrUX data
});

performance_record
- 记录性能追踪数据

typescript

// 记录页面加载过程
await use_mcp_tool("chrome-devtools", "performance_record", {
  url: "https://example.com",
  duration: 10000, // 10秒
  throttling: "4g" // 模拟4G网络
});

performance_analyze
- 分析性能指标

typescript

// 获取性能洞察
await use_mcp_tool("chrome-devtools", "performance_analyze", {
  traceUrl: "trace-data-url",
  includeFieldData: true // 包含CrUX数据
});

Debugging & Inspection

调试与检查

browser_console
- Get console messages

typescript

// Fetch console logs
await use_mcp_tool("chrome-devtools", "browser_console", {});

browser_network
- Inspect network requests

typescript

// Get network activity
await use_mcp_tool("chrome-devtools", "browser_network", {});

// Filter by resource type
await use_mcp_tool("chrome-devtools", "browser_network", {
  resourceType: "xhr"
});

browser_cookies
- Manage cookies

typescript

// Get all cookies
await use_mcp_tool("chrome-devtools", "browser_cookies", {
  action: "get"
});

// Set a cookie
await use_mcp_tool("chrome-devtools", "browser_cookies", {
  action: "set",
  name: "session_id",
  value: "abc123",
  domain: "example.com"
});

// Delete cookies
await use_mcp_tool("chrome-devtools", "browser_cookies", {
  action: "delete",
  name: "session_id"
});

browser_console
- 获取控制台消息

typescript

// 获取控制台日志
await use_mcp_tool("chrome-devtools", "browser_console", {});

browser_network
- 检查网络请求

typescript

// 获取网络活动数据
await use_mcp_tool("chrome-devtools", "browser_network", {});

// 按资源类型过滤
await use_mcp_tool("chrome-devtools", "browser_network", {
  resourceType: "xhr"
});

browser_cookies
- 管理Cookie

typescript

// 获取所有Cookie
await use_mcp_tool("chrome-devtools", "browser_cookies", {
  action: "get"
});

// 设置Cookie
await use_mcp_tool("chrome-devtools", "browser_cookies", {
  action: "set",
  name: "session_id",
  value: "abc123",
  domain: "example.com"
});

// 删除Cookie
await use_mcp_tool("chrome-devtools", "browser_cookies", {
  action: "delete",
  name: "session_id"
});

Common Automation Patterns

常见自动化模式

Form Submission Testing

表单提交测试

typescript

// Navigate to login page
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://app.example.com/login"
});

// Fill in credentials
await use_mcp_tool("chrome-devtools", "browser_type", {
  selector: "input[name='email']",
  text: "test@example.com"
});

await use_mcp_tool("chrome-devtools", "browser_type", {
  selector: "input[name='password']",
  text: process.env.TEST_PASSWORD
});

// Submit form
await use_mcp_tool("chrome-devtools", "browser_click", {
  selector: "button[type='submit']",
  waitUntil: "networkidle0"
});

// Verify success
const result = await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: "document.querySelector('.success-message')?.textContent"
});

typescript

// 导航到登录页面
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://app.example.com/login"
});

// 填写凭证
await use_mcp_tool("chrome-devtools", "browser_type", {
  selector: "input[name='email']",
  text: "test@example.com"
});

await use_mcp_tool("chrome-devtools", "browser_type", {
  selector: "input[name='password']",
  text: process.env.TEST_PASSWORD
});

// 提交表单
await use_mcp_tool("chrome-devtools", "browser_click", {
  selector: "button[type='submit']",
  waitUntil: "networkidle0"
});

// 验证提交成功
const result = await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: "document.querySelector('.success-message')?.textContent"
});

Web Scraping

Web数据爬取

typescript

// Navigate to page
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://news.example.com"
});

// Extract data
const articles = await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: `
    Array.from(document.querySelectorAll('article')).map(article => ({
      title: article.querySelector('h2')?.textContent?.trim(),
      link: article.querySelector('a')?.href,
      date: article.querySelector('time')?.getAttribute('datetime'),
      summary: article.querySelector('p')?.textContent?.trim()
    }))
  `
});

typescript

// 导航到目标页面
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://news.example.com"
});

// 提取数据
const articles = await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: `
    Array.from(document.querySelectorAll('article')).map(article => ({
      title: article.querySelector('h2')?.textContent?.trim(),
      link: article.querySelector('a')?.href,
      date: article.querySelector('time')?.getAttribute('datetime'),
      summary: article.querySelector('p')?.textContent?.trim()
    }))
  `
});

Performance Audit

性能审计

typescript

// Record trace with throttling
const trace = await use_mcp_tool("chrome-devtools", "performance_record", {
  url: "https://example.com",
  duration: 15000,
  throttling: "3g",
  deviceEmulation: "mobile"
});

// Analyze metrics
const analysis = await use_mcp_tool("chrome-devtools", "performance_analyze", {
  traceUrl: trace.url,
  includeFieldData: true
});

// Check Core Web Vitals
console.log(`LCP: ${analysis.lcp}ms`);
console.log(`FID: ${analysis.fid}ms`);
console.log(`CLS: ${analysis.cls}`);

typescript

// 带网络节流的性能追踪
const trace = await use_mcp_tool("chrome-devtools", "performance_record", {
  url: "https://example.com",
  duration: 15000,
  throttling: "3g",
  deviceEmulation: "mobile"
});

// 分析性能指标
const analysis = await use_mcp_tool("chrome-devtools", "performance_analyze", {
  traceUrl: trace.url,
  includeFieldData: true
});

// 查看核心Web指标
console.log(`LCP: ${analysis.lcp}ms`);
console.log(`FID: ${analysis.fid}ms`);
console.log(`CLS: ${analysis.cls}`);

Network Monitoring

网络监控

typescript

// Navigate and monitor network
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://api.example.com/dashboard"
});

// Get network requests
const requests = await use_mcp_tool("chrome-devtools", "browser_network", {});

// Filter failed requests
const failed = requests.filter(r => r.status >= 400);

// Find slow requests
const slow = requests.filter(r => r.time > 1000);

typescript

// 导航并监控网络
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://api.example.com/dashboard"
});

// 获取网络请求数据
const requests = await use_mcp_tool("chrome-devtools", "browser_network", {});

// 筛选失败请求
const failed = requests.filter(r => r.status >= 400);

// 筛选慢请求
const slow = requests.filter(r => r.time > 1000);

Screenshot Comparison

截图对比

typescript

// Baseline screenshot
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://example.com"
});

const baseline = await use_mcp_tool("chrome-devtools", "browser_screenshot", {
  fullPage: true
});

// Make changes via evaluate
await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: "document.body.classList.add('dark-mode')"
});

// Comparison screenshot
const comparison = await use_mcp_tool("chrome-devtools", "browser_screenshot", {
  fullPage: true
});

typescript

// 基准截图
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://example.com"
});

const baseline = await use_mcp_tool("chrome-devtools", "browser_screenshot", {
  fullPage: true
});

// 通过evaluate修改页面
await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: "document.body.classList.add('dark-mode')"
});

// 对比截图
const comparison = await use_mcp_tool("chrome-devtools", "browser_screenshot", {
  fullPage: true
});

Console Error Debugging

控制台错误调试

typescript

// Navigate to page
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://app.example.com"
});

// Check console for errors
const console = await use_mcp_tool("chrome-devtools", "browser_console", {});

// Filter errors with source maps
const errors = console.filter(msg => 
  msg.type === 'error' && msg.stackTrace
);

// Log error details
errors.forEach(error => {
  console.log(`Error: ${error.text}`);
  console.log(`Source: ${error.stackTrace?.[0]?.url}`);
  console.log(`Line: ${error.stackTrace?.[0]?.lineNumber}`);
});

typescript

// 导航到页面
await use_mcp_tool("chrome-devtools", "browser_navigate", {
  url: "https://app.example.com"
});

// 检查控制台错误
const console = await use_mcp_tool("chrome-devtools", "browser_console", {});

// 筛选带源码映射的错误
const errors = console.filter(msg => 
  msg.type === 'error' && msg.stackTrace
);

// 打印错误详情
errors.forEach(error => {
  console.log(`Error: ${error.text}`);
  console.log(`Source: ${error.stackTrace?.[0]?.url}`);
  console.log(`Line: ${error.stackTrace?.[0]?.lineNumber}`);
});

Configuration Options

配置选项

Command-Line Flags

命令行参数

bash

undefined

bash

undefined

Run in headless mode

无头模式运行

npx chrome-devtools-mcp@latest --headless

Slim mode (basic tools only)

精简模式（仅基础工具）

npx chrome-devtools-mcp@latest --slim

Disable performance CrUX data

禁用性能CrUX数据

npx chrome-devtools-mcp@latest --no-performance-crux

Disable usage statistics

禁用使用统计

npx chrome-devtools-mcp@latest --no-usage-statistics

Connect to existing browser

连接到已运行的浏览器

npx chrome-devtools-mcp@latest --browser-url=http://127.0.0.1:9222

Custom Chrome path

自定义Chrome路径

npx chrome-devtools-mcp@latest --chrome-path=/path/to/chrome

undefined

npx chrome-devtools-mcp@latest --chrome-path=/path/to/chrome

undefined

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

CI mode (disables stats collection)

CI模式（禁用统计收集）

export CI=true

undefined

export CI=true

undefined

MCP Server Configuration Examples

MCP服务器配置示例

Headless with custom timeout:

json

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

Connect to existing browser (Antigravity):

json

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

Windows configuration:

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "chrome-devtools-mcp@latest"
      ],
      "env": {
        "SystemRoot": "C:\\Windows",
        "PROGRAMFILES": "C:\\Program Files"
      }
    }
  }
}

带自定义超时的无头模式：

json

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

连接到已运行的浏览器（Antigravity）：

json

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

Windows系统配置：

json

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "chrome-devtools-mcp@latest"
      ],
      "env": {
        "SystemRoot": "C:\\Windows",
        "PROGRAMFILES": "C:\\Program Files"
      }
    }
  }
}

Troubleshooting

故障排查

Browser Won't Start

浏览器无法启动

Issue: Chrome fails to launch

Solution:

Verify Chrome is installed:
```
chrome --version
```
or
```
google-chrome --version
```
Check Node.js version:
```
node --version
```
(must be 20.19+)

Use explicit Chrome path:

json

{
  "args": ["-y", "chrome-devtools-mcp@latest", "--chrome-path=/usr/bin/google-chrome"]
}

问题： Chrome启动失败

解决方案：

验证Chrome已安装：
```
chrome --version
```
或
```
google-chrome --version
```
检查Node.js版本：
```
node --version
```
（必须为20.19+）

使用明确的Chrome路径：

json

{
  "args": ["-y", "chrome-devtools-mcp@latest", "--chrome-path=/usr/bin/google-chrome"]
}

Connection Timeout

连接超时

Issue: MCP server fails to connect to browser

Solution:

Increase startup timeout in config:
json
```
{
  "startup_timeout_ms": 20000
}
```
Check if another Chrome instance is using port 9222
Kill existing Chrome processes:
```
pkill chrome
```
(Linux/Mac)

问题： MCP服务器无法连接到浏览器

解决方案：

在配置中增加启动超时时间：
json
```
{
  "startup_timeout_ms": 20000
}
```
检查是否有其他Chrome实例占用9222端口
终止现有Chrome进程：
```
pkill chrome
```
（Linux/Mac）

Selector Not Found

选择器未找到

Issue:

browser_click

browser_type

fails to find element

Solution:

Wait for element to appear:

typescript

await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: `
    await new Promise(resolve => {
      const check = setInterval(() => {
        if (document.querySelector('#my-element')) {
          clearInterval(check);
          resolve();
        }
      }, 100);
    });
  `
});

Use more specific selectors (ID > class > tag)
Check if element is in iframe (not currently supported)

问题：

browser_click

或

browser_type

无法找到元素

解决方案：

等待元素加载完成：

typescript

await use_mcp_tool("chrome-devtools", "browser_evaluate", {
  script: `
    await new Promise(resolve => {
      const check = setInterval(() => {
        if (document.querySelector('#my-element')) {
          clearInterval(check);
          resolve();
        }
      }, 100);
    });
  `
});

使用更具体的选择器（ID > 类 > 标签）
检查元素是否在iframe中（当前暂不支持）

Performance Trace Fails

性能追踪失败

Issue:

performance_record

returns incomplete trace

Solution:

Increase duration:
```
duration: 30000
```
Disable throttling for local testing: remove
```
throttling
```
parameter
Check network connectivity for remote URLs

问题：

performance_record

返回不完整的追踪数据

解决方案：

增加追踪时长：
```
duration: 30000
```
本地测试时禁用网络节流：移除
```
throttling
```
参数
检查远程URL的网络连通性

Source Maps Not Loading

源码映射未加载

Issue: Console errors don't show source-mapped stack traces

Solution:

Ensure source maps are published with your build
Verify source map URLs are accessible
Check CORS headers on source map files

问题： 控制台错误未显示源码映射的堆栈跟踪

解决方案：

确保构建产物中包含源码映射文件
验证源码映射URL可访问
检查源码映射文件的CORS头

High Memory Usage

内存占用过高

Issue: Chrome consumes excessive memory

Solution:

Use
```
--headless
```
mode
Close browser between test runs
Use
```
--slim
```
mode if you don't need performance tools
Limit trace duration in
```
performance_record
```

问题： Chrome消耗过多内存

解决方案：

使用
```
--headless
```
模式
测试运行后关闭浏览器
若无需性能工具，使用
```
--slim
```
模式
限制
```
performance_record
```
的追踪时长

Rate Limiting (CrUX API)

CrUX API速率限制

Issue: Performance analysis fails with rate limit error

Solution:

Disable CrUX:
```
--no-performance-crux
```
Cache analysis results for repeated URLs
Add delay between performance audits

问题： 性能分析因速率限制失败

解决方案：

禁用CrUX：
```
--no-performance-crux
```
缓存重复URL的分析结果
性能审计之间增加延迟

Best Practices

最佳实践

Always use headless mode in CI/CD: Add
```
--headless
```
flag
Use environment variables for sensitive data: Never hardcode credentials
Wait for navigation: Use
```
waitUntil: "networkidle0"
```
for SPAs
Cache selectors: Store frequently used selectors as constants
Clean up resources: Close browser instances after automation completes
Enable source maps: For better debugging of console errors
Use slim mode for simple tasks: Faster startup, lower memory usage
Throttle performance tests: Simulate real-world conditions with
```
throttling: "4g"
```

CI/CD中始终使用无头模式：添加
```
--headless
```
参数
使用环境变量存储敏感数据：切勿硬编码凭证
等待导航完成：针对单页应用使用
```
waitUntil: "networkidle0"
```
缓存选择器：将常用选择器存储为常量
清理资源：自动化完成后关闭浏览器实例
启用源码映射：便于调试控制台错误
简单任务使用精简模式：启动更快，内存占用更低
节流性能测试：使用
```
throttling: "4g"
```
模拟真实环境