Chrome DevTools MCP Server
一个基于 Model Context Protocol (MCP) 的 Chrome DevTools 控制服务器，为 AI 辅助前端开发提供强大的浏览器调试能力。
功能特性
本项目提供了一套完整的 Chrome 浏览器控制工具，让 AI 能够：
- 🚀 启动和控制 Chrome 浏览器 - 自动启动开发环境的 Chrome 实例
- 🔗 远程连接 CDP - 连接到已运行的 Chrome、Electron 或其他 V8 内核程序
- 🔍 DOM 查询和分析 - 获取页面 DOM 树结构，查询特定元素
- 🌐 网络请求监控 - 实时捕获和分析所有网络请求和响应
- 📝 Console 日志捕获 - 获取所有控制台输出，包括错误、警告和日志
- 💻 JavaScript 执行 - 在页面上下文中执行任意 JavaScript 代码
- 🎯 页面导航 - 控制浏览器导航到指定 URL
- 📸 截图功能 - 捕获当前页面的截图
- ℹ️ 页面信息获取 - 获取页面标题、URL、元数据等信息
- 🐛 JavaScript 断点调试 - 设置各种类型的断点，支持条件断点
- 🎮 调试控制 - 暂停、继续、单步执行等调试操作
第一部分：开发、安装和启动
环境要求
- Python 3.7+
- Google Chrome 浏览器
- macOS/Linux/Windows
安装步骤
- 克隆项目：
git clone https://github.com/yourusername/chrome-devtool-mcp.git
cd chrome-devtool-mcp
- 创建虚拟环境（推荐）：
python -m venv venv
source venv/bin/activate # macOS/Linux
# 或
venv\Scripts\activate # Windows
- 安装依赖：
pip install -r requirements.txt
启动服务器
使用以下命令启动服务器：
python src/chrome_devtools_mcp.py
或使用启动脚本：
./start.sh
服务器将在 http://localhost:12524 启动。
自定义端口
如果需要使用其他端口，修改脚本中的端口号或设置环境变量：
MCP_PORT=8080 python src/chrome_devtools_mcp.py
第二部分：Claude Code 接入指南
方法一：使用 MCP 配置文件
- 创建或编辑 Claude Code 的 MCP 配置文件：
macOS/Linux:
mkdir -p ~/.config/claude/mcp
nano ~/.config/claude/mcp/chrome-devtools.json
Windows:
mkdir -p $env:APPDATA\claude\mcp
notepad $env:APPDATA\claude\mcp\chrome-devtools.json
- 添加以下配置：
{
"mcpServers": {
"chrome-devtools": {
"command": "python",
"args": ["/path/to/chrome-devtool-mcp/mcp_server.py"],
"env": {}
}
}
}
- 重启 Claude Code 以加载配置。
方法二：在已接入 agent 的情况下启动
如果你已经有其他 MCP 服务器在运行，可以通过以下方式添加 Chrome DevTools 服务器：
- 修改现有的 MCP 配置文件，添加 chrome-devtools 配置：
{
"mcpServers": {
"existing-server": {
// ... 现有配置
},
"chrome-devtools": {
"command": "python",
"args": ["/path/to/chrome-devtool-mcp/mcp_server.py"],
"env": {}
}
}
}
- 或者使用环境变量方式：
export CLAUDE_MCP_CHROME_DEVTOOLS="python /path/to/chrome-devtool-mcp/mcp_server.py"
claude-code
验证接入
在 Claude Code 中，你可以通过以下方式验证工具是否成功接入：
请列出所有可用的 MCP 工具
你应该能看到以下工具：
- launch_chrome
- connect_remote_chrome
- connect_websocket_url
- list_available_targets
- navigate_to
- get_dom_tree
- query_elements
- get_network_logs
- get_console_logs
- execute_javascript
- take_screenshot
- get_page_info
- get_script_sources
- get_script_source
- search_in_scripts
- get_page_functions
- set_breakpoint
- list_breakpoints
- remove_breakpoint
- get_paused_info
- resume_execution
- step_over
- close_chrome
第三部分：Cursor 接入指南
方法一：通过配置文件接入（推荐）
-
首先确保 MCP 服务器已启动：
python simple_mcp_server.py # 服务器运行在 http://localhost:12524 -
打开 Cursor 设置（
Cmd+,或Ctrl+,） -
搜索 "Model Context Protocol" 或 "MCP"
-
在 MCP 配置中添加：
{ "mcpServers": { "chrome-devtools": { "command": "python3", "args": ["/path/to/chrome-devtool-mcp/src/chrome_devtools_mcp.py"] } } } -
重启 Cursor 以加载 MCP 工具
方法二：使用环境变量配置
如果需要自定义端口或主机：
-
设置环境变量并启动服务器：
MCP_PORT=8080 MCP_HOST=127.0.0.1 python src/chrome_devtools_mcp.py -
在 Cursor 配置中使用相应的端口：
{ "mcpServers": { "chrome-devtools": { "command": "python3", "args": ["/path/to/chrome-devtool-mcp/src/chrome_devtools_mcp.py"], "env": { "MCP_PORT": "8080", "MCP_HOST": "127.0.0.1" } } } }
验证连接
连接成功后，你可以在 Cursor 中：
- 使用
@符号查看可用的 MCP 工具 - 或者询问 "列出所有可用的 Chrome DevTools 工具"
你应该能看到以下工具：
- launch_chrome
- connect_remote_chrome
- connect_websocket_url
- list_available_targets
- navigate_to
- get_dom_tree
- query_elements
- get_network_logs
- get_console_logs
- execute_javascript
- take_screenshot
- get_page_info
- get_script_sources
- get_script_source
- search_in_scripts
- get_page_functions
- set_breakpoint
- list_breakpoints
- remove_breakpoint
- get_paused_info
- resume_execution
- step_over
- close_chrome
故障排除
如果无法连接：
-
确保服务器正在运行：
curl http://localhost:12524/health -
检查防火墙设置，确保端口 12524 可访问
-
查看服务器日志了解详细错误信息
-
尝试在浏览器中访问
http://localhost:12524/docs查看 API 文档
使用示例
基础使用流程
- 启动 Chrome：
使用 launch_chrome 工具启动一个 Chrome 浏览器实例
- 导航到目标页面：
使用 navigate_to 工具访问 http://localhost:3000
- 检查页面结构：
使用 get_dom_tree 工具获取页面的 DOM 结构
- 查询特定元素：
使用 query_elements 工具查找所有 class 为 "button" 的元素
- 监控网络请求：
使用 get_network_logs 工具查看所有 API 请求
- 执行 JavaScript：
使用 execute_javascript 工具在页面上执行 console.log('Hello from AI!')
高级调试场景
场景1：调试 React 应用的状态
1. 启动 Chrome 并导航到 React 应用
2. 使用 execute_javascript 执行：
window.__REACT_DEVTOOLS_GLOBAL_HOOK__.renderers.values().next().value.findFiberByHostInstance(document.querySelector('#root'))._debugOwner.stateNode.state
3. 分析返回的状态数据
场景2：监控和分析 API 调用
1. 清空网络日志
2. 触发应用中的某个操作
3. 使用 get_network_logs 筛选特定 API 端点
4. 分析请求和响应数据
场景3：性能分析
1. 使用 execute_javascript 执行 performance.mark('start')
2. 执行一系列操作
3. 使用 execute_javascript 执行 performance.mark('end') 和 performance.measure('operation', 'start', 'end')
4. 获取性能数据
场景4：调试登录按钮点击事件
1. 使用 connect_remote_chrome 连接到已运行的应用
2. 使用 query_elements 找到登录按钮选择器（如 '#login-btn'）
3. 使用 set_breakpoint('dom', '#login-btn') 在登录按钮上设置断点
4. 点击登录按钮，调试器会暂停
5. 使用 get_console_logs 查看控制台输出
6. 使用 get_paused_info 查看暂停位置和调用栈
7. 使用 resume_execution 继续执行
场景5：调试远程 Electron 应用
1. 启动 Electron 应用时添加 --remote-debugging-port=9222 参数
2. 使用 connect_remote_chrome('localhost', 9222) 连接
3. 使用各种调试工具进行分析
4. 设置断点并调试特定功能
场景6：在多个标签页之间切换
1. 使用 list_available_targets() 列出所有可用的标签页
2. 选择目标标签页的 webSocketDebuggerUrl
3. 使用 connect_websocket_url(ws_url) 切换到该标签页
4. 现在所有操作都会在新的标签页上执行
示例代码：
# 列出所有标签页
targets = list_available_targets()
# 选择第二个标签页
ws_url = targets['data']['targets'][1]['webSocketDebuggerUrl']
# 切换到该标签页
connect_websocket_url(ws_url)
API 工具详细说明
launch_chrome
启动 Chrome 浏览器实例，支持 headless 模式。
参数：
headless(bool): 是否无头模式运行，默认 falseport(int): 远程调试端口，默认 9222
connect_remote_chrome
连接到远程 Chrome/Chromium 实例（如 Electron 应用）。
参数：
host(str): 远程主机地址，默认 localhostport(int): 远程调试端口，默认 9222
connect_websocket_url
直接使用 WebSocket URL 连接到特定的调试会话。
参数：
ws_url(str): WebSocket 调试器 URL，如 'ws://localhost:9222/devtools/page/ABC123'
使用场景：
- 切换不同的标签页/页面
- 连接到特定的调试会话
- 从其他工具获取的 WebSocket URL
list_available_targets
列出所有可用的 Chrome 标签页/页面及其 WebSocket URL。
参数：
host(str): Chrome 主机地址，默认 localhostport(int): Chrome 调试端口，默认 9222
navigate_to
导航到指定 URL。
参数：
url(str): 目标 URL
get_dom_tree
获取当前页面的 DOM 树结构。
参数：
depth(int): DOM 树的最大深度，默认 3
query_elements
使用 CSS 选择器查询 DOM 元素。
参数：
selector(str): CSS 选择器
get_network_logs
获取网络请求日志。
参数：
filter_url(str, optional): URL 过滤模式
get_console_logs
获取控制台日志。
参数：
level(str, optional): 日志级别过滤（error, warning, log, info）
execute_javascript
在页面上下文中执行 JavaScript 代码。
参数：
code(str): 要执行的 JavaScript 代码
take_screenshot
截取当前页面的屏幕截图。
参数：
full_page(bool): 是否截取整个页面，默认 false
get_page_info
获取当前页面的基本信息。
无参数。
close_chrome
关闭 Chrome 浏览器实例。
无参数。
set_breakpoint
设置 JavaScript 断点。支持传统断点和日志断点（logpoint）。
参数：
breakpoint_type(str): 断点类型 - 'dom', 'event', 'function', 'xhr', 'line', 'logpoint'target(str): 断点目标（如 DOM 选择器、函数名、URL:行号）options(dict, optional): 额外选项condition: 条件表达式，只在条件为真时触发logMessage: 日志消息（用于日志断点）pause: 是否暂停执行（默认：logpoint 为 False，其他为 True）
示例：
- DOM 断点：
set_breakpoint('dom', '#login-button') - 函数断点：
set_breakpoint('function', 'handleLogin') - 行断点：
set_breakpoint('line', 'app.js:42') - XHR 断点：
set_breakpoint('xhr', '/api/login') - 日志断点：
set_breakpoint('function', 'processData', {'logMessage': 'Processing data...', 'pause': False}) - 条件日志断点：
set_breakpoint('function', 'validate', {'condition': 'value < 0', 'logMessage': 'Invalid value', 'pause': False})
list_breakpoints
列出所有活动断点。
无参数。
remove_breakpoint
移除指定断点。
参数：
breakpoint_id(str): 断点 ID
get_paused_info
获取调试器暂停时的信息。
无参数。
resume_execution
从断点恢复执行。
无参数。
step_over
单步跳过当前行。
无参数。
get_script_sources
获取当前页面加载的所有 JavaScript 源代码列表。
无参数。
返回：
- scripts: 脚本列表，包含 scriptId、url、startLine、endLine
- count: 脚本总数
get_script_source
获取特定脚本的源代码。
参数：
script_id(str): 脚本 ID（从 get_script_sources 获取）
search_in_scripts
在所有加载的脚本中搜索函数、类或文本。
参数：
pattern(str): 搜索模式（如函数名、类名、文本）search_type(str): 搜索类型 - 'function'、'class'、'variable'、'text'
get_page_functions
获取页面中定义的所有函数。
无参数。
故障排除
Chrome 无法启动
- 确保 Chrome 已安装
- 检查端口 9222 是否被占用：
lsof -i :9222 # macOS/Linux netstat -an | findstr 9222 # Windows
WebSocket 连接失败
- 确保 Chrome 以调试模式启动
- 检查防火墙设置
- 尝试使用不同的端口
MCP 工具无法识别
- 确保 MCP 服务器正在运行
- 检查配置文件路径是否正确
- 重启 Claude Code 或 Cursor
贡献指南
欢迎提交 Issue 和 Pull Request！
许可证
本项目采用 MIT 许可证 开源。
MIT License - 详细信息请查看 LICENSE 文件。
该许可证允许您：
- ✅ 商业使用
- ✅ 修改
- ✅ 分发
- ✅ 私人使用
只要您：
- 📄 包含版权声明和许可证声明
- 📝 说明所做的更改（如有修改）