chrome-devtools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Chrome DevTools MCP Skill

Chrome DevTools MCP 技能

Control Chrome browser programmatically via chrome-devtools-mcp.

⚡ Performance Tip: Always use the patterns in "Quick Start" section below. They include cleanup and run everything in ONE command to avoid browser lock issues.

Speed Comparison:

❌ OLD WAY: Multiple attempts, manual cleanup, 5-10 commands → ~60-90 seconds
✅ NEW WAY: One optimized command → ~5-10 seconds

📚 See also: MCP CLI Guide for general MCP CLI patterns and best practices

通过chrome-devtools-mcp以编程方式控制Chrome浏览器。

⚡ 性能提示： 请始终使用下方「快速开始」章节中的模式。这些模式包含清理操作，并将所有步骤整合为一个命令，以避免浏览器锁定问题。

速度对比：

❌ 旧方式： 多次尝试、手动清理、5-10条命令 → 约60-90秒
✅ 新方式： 一条优化后的命令 → 约5-10秒

📚 另请参阅： MCP CLI 指南，了解通用MCP CLI模式与最佳实践

Setup

安装设置

bash

undefined

bash

undefined

macOS

brew tap f/mcptools brew install mcp

Windows/Linux

go install github.com/f/mcptools/cmd/mcptools@latest

undefined

go install github.com/f/mcptools/cmd/mcptools@latest

undefined

Quick Start (FASTEST)

快速开始（最快方式）

Check Console Errors on localhost

检查localhost的控制台错误

Single command (copy-paste ready):

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nlist_console_messages {"pageIdx":0}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

单条命令（可直接复制粘贴）：

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nlist_console_messages {"pageIdx":0}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Full Debug: Console + Network + Page Content

完整调试：控制台 + 网络 + 页面内容

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nlist_console_messages {"pageIdx":0}\nlist_network_requests {"pageIdx":0}\ntake_snapshot {"verbose":true}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nlist_console_messages {"pageIdx":0}\nlist_network_requests {"pageIdx":0}\ntake_snapshot {"verbose":true}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Screenshot a Page

截取页面截图

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"https://example.com"}\ntake_screenshot {"fullPage":true,"format":"png"}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"https://example.com"}\ntake_screenshot {"fullPage":true,"format":"png"}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Execute JavaScript on Page

在页面中执行JavaScript

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nevaluate_script {"function":"() => document.querySelectorAll(\"div\").length"}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

⚡ Pattern:

cleanup; sleep; echo commands | timeout shell

This avoids:

❌ Browser profile locks (cleanup first)
❌ Multiple shell sessions (one pipeline)
❌ Hanging commands (timeout wrapper)

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1; echo -e 'navigate_page {"url":"http://localhost:3000"}\nevaluate_script {"function":"() => document.querySelectorAll(\"div\").length"}\nexit' | timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

⚡ 模式：

cleanup; sleep; echo commands | timeout shell

这种模式可避免：

❌ 浏览器配置文件锁定（先执行清理）
❌ 多个Shell会话（单条管道命令）
❌ 命令挂起（超时包装）

Usage

使用方法

List available tools:

bash

mcp tools bunx -y chrome-devtools-mcp@latest

Call tools (individual commands):

bash

undefined

列出可用工具：

bash

mcp tools bunx -y chrome-devtools-mcp@latest

调用工具（单个命令）：

bash

undefined

Navigate to a page (includes page list in response)

导航到页面（响应中包含页面列表）

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"https://example.com"}'

Take screenshot

截取截图

mcp call take_screenshot bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"fullPage":true,"format":"png"}'

Take snapshot (page content as text)

生成快照（页面内容为文本格式）

mcp call take_snapshot bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"verbose":false}'

List console messages

列出控制台消息

mcp call list_console_messages bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"pageIdx":0}'

Execute JavaScript

执行JavaScript

mcp call evaluate_script bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"function":"() => document.title"}'


**Interactive shell mode (RECOMMENDED - maintains single browser instance):**
```bash
mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

mcp call evaluate_script bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"function":"() => document.title"}'


**交互式Shell模式（推荐 - 维持单个浏览器实例）：**
```bash
mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Then run commands:

然后运行命令：

navigate_page {"url":"https://example.com"} take_snapshot {"verbose":false} list_console_messages {"pageIdx":0} new_page {"url":"https://httpbin.org"} exit


**With Chrome launch options:**
```bash

navigate_page {"url":"https://example.com"} take_snapshot {"verbose":false} list_console_messages {"pageIdx":0} new_page {"url":"https://httpbin.org"} exit


**搭配Chrome启动选项：**
```bash

Headless mode

无头模式

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --headless --isolated --params '{"url":"https://example.com"}'

Custom viewport

自定义视口

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --viewport "1920x1080" --isolated --params '{"url":"https://example.com"}'

Connect to existing Chrome instance (no --isolated needed)

连接到已运行的Chrome实例（无需--isolated）

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --browserUrl http://127.0.0.1:9222 --params '{"url":"https://example.com"}'

undefined

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --browserUrl http://127.0.0.1:9222 --params '{"url":"https://example.com"}'

undefined

Common Workflows

常见工作流程

Check localhost console logs:

bash

undefined

检查localhost控制台日志：

bash

undefined

Shell mode (RECOMMENDED):

Shell模式（推荐）：

mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Then: navigate_page {"url":"http://localhost:3000"}

然后：navigate_page {"url":"http://localhost:3000"}

Then: list_console_messages {"pageIdx":0}

然后：list_console_messages {"pageIdx":0}

Or as individual commands:

或作为单个命令：

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"http://localhost:3000"}' mcp call list_console_messages bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"pageIdx":0}'


**Automate form filling:**
```bash
mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated


**自动化表单填充：**
```bash
mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Then in shell:

然后在Shell中运行：

navigate_page {"url":"https://example.com/login"}

take_snapshot {"verbose":false} # Get UIDs for elements

take_snapshot {"verbose":false} # 获取元素的UID

fill {"uid":"#username","value":"user"}

fill {"uid":"#password","value":"pass"}

click {"uid":"#submit"}


**Network debugging:**
```bash


**网络调试：**
```bash

Shell mode (RECOMMENDED):

Shell模式（推荐）：

mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Then: navigate_page {"url":"https://example.com"}

然后：navigate_page {"url":"https://example.com"}

Then: list_network_requests {"pageIdx":0}

然后：list_network_requests {"pageIdx":0}

Or as individual commands:

或作为单个命令：

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"https://example.com"}' mcp call list_network_requests bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"pageIdx":0}'

undefined

undefined

Key Tools

核心工具

navigate_page - Go to URL (returns page list)
new_page - Open new tab (returns page list)
select_page - Switch to different page by index
close_page - Close page by index
click - Click element
fill - Fill input/textarea
evaluate_script - Run JavaScript
take_screenshot - Capture page as image
take_snapshot - Get page content as text with UIDs
list_console_messages - View console logs (use
```
{"pageIdx":0}
```
)
list_network_requests - View network activity (use
```
{"pageIdx":0}
```
)
wait_for - Wait for text/condition

navigate_page - 导航到指定URL（返回页面列表）
new_page - 打开新标签页（返回页面列表）
select_page - 通过索引切换到不同页面
close_page - 通过索引关闭页面
click - 点击元素
fill - 填充输入框/文本域
evaluate_script - 运行JavaScript
take_screenshot - 将页面捕获为图片
take_snapshot - 获取带UID的页面文本内容
list_console_messages - 查看控制台日志（使用
```
{"pageIdx":0}
```
）
list_network_requests - 查看网络活动（使用
```
{"pageIdx":0}
```
）
wait_for - 等待文本/条件满足

Important Notes

重要注意事项

Always use
```
bunx
```
(not
```
npx
```
) for chrome-devtools-mcp
Correct syntax:
```
mcp call TOOL_NAME bunx -y chrome-devtools-mcp@latest -- --isolated --params '{...}'
```
- Server command comes AFTER tool name, BEFORE --params
- Parameters are passed directly (no "arguments" wrapper)
- Use
```
-- --isolated
```
  to create temporary profile (prevents browser lock conflicts)
Server exposes full browser content - avoid sensitive data

请始终使用
```
bunx
```
而非
```
npx
```
来运行chrome-devtools-mcp
正确语法：
```
mcp call TOOL_NAME bunx -y chrome-devtools-mcp@latest -- --isolated --params '{...}'
```
- 服务器命令需放在工具名称之后，--params之前
- 参数直接传递（无需"arguments"包装）
- 使用
```
-- --isolated
```
  创建临时配置文件（避免浏览器锁定冲突）
服务器会暴露完整浏览器内容 - 请避免处理敏感数据

Working with Multiple Commands

多命令协作

Problem: Each

mcp call

starts a new server & browser instance, causing conflicts.

Solutions:

Shell mode (RECOMMENDED): Maintains single browser instance
bash
```
mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated
```

Individual calls: Use

-- --isolated

for one-off commands

bash

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"..."}'

Connect to running Chrome: Start Chrome with debugging enabled

bash

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --browserUrl http://127.0.0.1:9222 --params '{"url":"..."}'

问题： 每次

mcp call

都会启动新的服务器和浏览器实例，导致冲突。

解决方案：

Shell模式（推荐）： 维持单个浏览器实例

bash

mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

单个命令调用： 对一次性命令使用

-- --isolated

bash

mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --isolated --params '{"url":"..."}'

连接到已运行的Chrome： 启动Chrome并开启调试模式

bash

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
mcp call navigate_page bunx -y chrome-devtools-mcp@latest -- --browserUrl http://127.0.0.1:9222 --params '{"url":"..."}'

Known Issues (mcp CLI v0.7.1)

已知问题（mcp CLI v0.7.1）

⚠️ Bug: Tools with empty parameter schemas fail with "Invalid arguments" error.

Workaround: Provide at least one optional parameter:

✅
```
list_console_messages {"pageIdx":0}
```
- Works
✅
```
list_network_requests {"pageIdx":0}
```
- Works
✅
```
take_snapshot {"verbose":false}
```
- Works
❌
```
list_pages
```
- Broken, use
```
navigate_page
```
or
```
new_page
```
instead (they return page list)

⚠️ Bug： 参数架构为空的工具会因「无效参数」错误而失败。

解决方法： 至少提供一个可选参数：

✅
```
list_console_messages {"pageIdx":0}
```
- 可正常工作
✅
```
list_network_requests {"pageIdx":0}
```
- 可正常工作
✅
```
take_snapshot {"verbose":false}
```
- 可正常工作
❌
```
list_pages
```
- 无法使用，请改用
```
navigate_page
```
或
```
new_page
```
（它们会返回页面列表）

Troubleshooting

故障排除

Problem: "The browser is already running" error

This happens when a previous Chrome instance is still holding the profile lock.

Quick fix (ALWAYS DO THIS FIRST):

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1

Then run your command:

bash

echo -e 'navigate_page {"url":"YOUR_URL"}\nlist_console_messages {"pageIdx":0}\nexit' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Problem: Multiple failed attempts

Don't create multiple shell sessions - keep ONE session open and run multiple commands:

❌ BAD (slow - 2 separate sessions):

bash

echo 'navigate_page {"url":"..."}' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated
echo 'list_console_messages {"pageIdx":0}' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

✅ GOOD (fast - 1 session, multiple commands):

bash

echo -e 'navigate_page {"url":"..."}\nlist_console_messages {"pageIdx":0}\nexit' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

Problem: Commands hanging/timing out

Use

timeout

to prevent hanging:

bash

timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

问题： 出现「浏览器已在运行」错误

这是因为之前的Chrome实例仍持有配置文件锁定。

快速修复（请始终先执行此操作）：

bash

pkill -9 -f "chrome-devtools-mcp" 2>/dev/null; sleep 1

然后运行你的命令：

bash

echo -e 'navigate_page {"url":"YOUR_URL"}\nlist_console_messages {"pageIdx":0}\nexit' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

问题： 多次尝试失败

不要创建多个Shell会话 - 保持一个会话打开并运行多条命令：

❌ 错误方式（速度慢 - 2个独立会话）：

bash

echo 'navigate_page {"url":"..."}' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated
echo 'list_console_messages {"pageIdx":0}' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

✅ 正确方式（速度快 - 1个会话，多条命令）：

bash

echo -e 'navigate_page {"url":"..."}\nlist_console_messages {"pageIdx":0}\nexit' | mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated

问题： 命令挂起/超时

使用

timeout

防止命令挂起：

bash

timeout 30 mcp shell bunx -y chrome-devtools-mcp@latest -- --isolated