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

安装步骤

1. 克隆项目：

git clone https://github.com/yourusername/chrome-devtool-mcp.git cd chrome-devtool-mcp

1. 创建虚拟环境（推荐）：

python -m venv venv source venv/bin/activate # macOS/Linux

或

venv\Scripts\activate # Windows

1. 安装依赖：

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 配置文件

1. 创建或编辑 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

1. 添加以下配置：

{ "mcpServers": { "chrome-devtools": { "command": "python", "args": ["/path/to/chrome-devtool-mcp/mcp_server.py"], "env": {} } } }

1. 重启 Claude Code 以加载配置。

方法二：在已接入 agent 的情况下启动

如果你已经有其他 MCP 服务器在运行，可以通过以下方式添加 Chrome DevTools 服务器：

1. 修改现有的 MCP 配置文件，添加 chrome-devtools 配置：

{ "mcpServers": { "existing-server": { // ... 现有配置 }, "chrome-devtools": { "command": "python", "args": ["/path/to/chrome-devtool-mcp/mcp_server.py"], "env": {} } } }

1. 或者使用环境变量方式：

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 接入指南

方法一：通过配置文件接入（推荐）

1. 首先确保 MCP 服务器已启动：
   python simple_mcp_server.py

服务器运行在 http://localhost:12524

2. 打开 Cursor 设置（Cmd+, 或 Ctrl+,）
3. 搜索 "Model Context Protocol" 或 "MCP"
4. 在 MCP 配置中添加：
   {
   "mcpServers": {
   "chrome-devtools": {
   "command": "python3",
   "args": ["/path/to/chrome-devtool-mcp/src/chrome_devtools_mcp.py"]
   }
   }
   }
5. 重启 Cursor 以加载 MCP 工具

方法二：使用环境变量配置

如果需要自定义端口或主机：

1. 设置环境变量并启动服务器：
   MCP_PORT=8080 MCP_HOST=127.0.0.1 python src/chrome_devtools_mcp.py
2. 在 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 中：

1. 使用 @ 符号查看可用的 MCP 工具
2. 或者询问 "列出所有可用的 Chrome DevTools 工具"

你应该能看到以下工具：

故障排除

如果无法连接：

1. 确保服务器正在运行：
   curl http://localhost:12524/health
2. 检查防火墙设置，确保端口 12524 可访问
3. 查看服务器日志了解详细错误信息
4. 尝试在浏览器中访问 http://localhost:12524/docs 查看 API 文档

使用示例

基础使用流程

1. 启动 Chrome：

使用 launch_chrome 工具启动一个 Chrome 浏览器实例

1. 导航到目标页面：

使用 navigate_to 工具访问 http://localhost:3000

1. 检查页面结构：

使用 get_dom_tree 工具获取页面的 DOM 结构

1. 查询特定元素：

使用 query_elements 工具查找所有 class 为 "button" 的元素

1. 监控网络请求：

使用 get_network_logs 工具查看所有 API 请求

1. 执行 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): 是否无头模式运行，默认 false
• port (int): 远程调试端口，默认 9222

connect_remote_chrome

连接到远程 Chrome/Chromium 实例（如 Electron 应用）。

参数：

• host (str): 远程主机地址，默认 localhost
• port (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 主机地址，默认 localhost
• port (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 无法启动

1. 确保 Chrome 已安装
2. 检查端口 9222 是否被占用：
   lsof -i :9222 # macOS/Linux
   netstat -an | findstr 9222 # Windows

WebSocket 连接失败

1. 确保 Chrome 以调试模式启动
2. 检查防火墙设置
3. 尝试使用不同的端口

MCP 工具无法识别

1. 确保 MCP 服务器正在运行
2. 检查配置文件路径是否正确
3. 重启 Claude Code 或 Cursor

贡献指南

欢迎提交 Issue 和 Pull Request！

许可证

本项目采用 MIT 许可证 开源。

MIT License - 详细信息请查看 LICENSE 文件。

该许可证允许您：

• ✅ 商业使用
• ✅ 修改
• ✅ 分发
• ✅ 私人使用

只要您：

• 📄 包含版权声明和许可证声明
• 📝 说明所做的更改（如有修改）

相关链接

• Chrome DevTools Protocol
• Model Context Protocol
• FastMCP