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. 克隆项目：

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

3. 安装依赖：

启动服务器

使用以下命令启动服务器：

或使用启动脚本：

服务器将在 http://localhost:12524 启动。

自定义端口

如果需要使用其他端口，修改脚本中的端口号或设置环境变量：

第二部分：Claude Code 接入指南

方法一：使用 MCP 配置文件

1. 创建或编辑 Claude Code 的 MCP 配置文件：

macOS/Linux:

Windows:

2. 添加以下配置：

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

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

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

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

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

验证接入

在 Claude Code 中，你可以通过以下方式验证工具是否成功接入：

你应该能看到以下工具：

• 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 工具"

你应该能看到以下工具：

• 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

故障排除

如果无法连接：

1. 确保服务器正在运行：

   curl http://localhost:12524/health

2. 检查防火墙设置，确保端口 12524 可访问

3. 查看服务器日志了解详细错误信息

4. 尝试在浏览器中访问 http://localhost:12524/docs 查看 API 文档

使用示例

基础使用流程

1. 启动 Chrome：

2. 导航到目标页面：

3. 检查页面结构：

4. 查询特定元素：

5. 监控网络请求：

6. 执行 JavaScript：

高级调试场景

场景1：调试 React 应用的状态

场景2：监控和分析 API 调用

场景3：性能分析

场景4：调试登录按钮点击事件

场景5：调试远程 Electron 应用

场景6：在多个标签页之间切换

示例代码：

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