Chrome DevTools MCP Server

  1. ALMC
  2. MCP
  3. development
  4. chrome-devtools-mcp-server
Chrome DevTools MCP Server - Secure MCP Server by ALMC Security 2025

Chrome DevTools MCP Server

View on GitHub

Chrome DevTools MCP Server

License: MIT

一个基于 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

  1. 打开 Cursor 设置（Cmd+, 或 Ctrl+,）
  2. 搜索 "Model Context Protocol" 或 "MCP"
  3. 在 MCP 配置中添加：
    {
    "mcpServers": {
    "chrome-devtools": {
    "command": "python3",
    "args": ["/path/to/chrome-devtool-mcp/src/chrome_devtools_mcp.py"]
    }
    }
    }
  4. 重启 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

Related in Development - Secure MCP Servers

ServerSummaryActions
Universal Infinite Loop MCP ServerA goal-agnostic parallel orchestration framework implementing Disler's Infinite Agentic Loop pattern...View
MCP HAR ServerA Model Context Protocol (MCP) server that parses HAR (HTTP Archive) files and displays requests in...View
mcp-registry-mcpMCP server for mcp-registry: https://github.com/modelcontextprotocol/registryView
Gemini CLI RAG MCPThis project builds a standalone RAG service, transforming the static gemini-cli documentation into...View
Swagger/OpenAPI MCP ServerA Model Context Protocol (MCP) server that allows LLMs to explore and interact with Swagger/OpenAPI...View
Python REPLThis MCP server provides a Python REPL (Read-Eval-Print Loop) as a tool. It allows execution of Pyth...View