Chrome Devtools Mcp

Chrome Devtools Mcp

开发 Python

🚀 Chrome DevTools MCP

Chrome DevTools MCP 是一个模型上下文协议（MCP）服务器，它通过 MCP 提供与 Chrome 开发者工具协议的集成。借助该服务器，你可以连接到 Chrome 的开发者工具，对 Web 应用程序进行调试。

支持作为 Claude 桌面扩展（.dxt）使用，轻松一键安装！

🚀 快速开始

在 Claude 桌面版中安装此工具后，你就可以开始调试任何 Web 应用程序：

调试你的 Web 应用程序

一步设置（推荐）：

start_chrome_and_connect("localhost:3000")

将 localhost:3000 替换为你的应用程序的 URL

如果无法自动找到 Chrome：

start_chrome_and_connect("localhost:3000", chrome_path="/path/to/chrome")

使用 chrome_path 参数指定自定义的 Chrome 位置

此命令将执行以下操作：

  • 启动启用调试功能的 Chrome
  • 导航到你的应用程序
  • 将 MCP 服务器连接到 Chrome

手动设置（如果你更喜欢分步操作）：

start_chrome()
navigate_to_url("localhost:3000")
connect_to_browser()

开始调试

连接成功后，你可以使用以下命令：

  • get_network_requests() - 查看 HTTP 流量
  • get_console_error_summary() - 分析 JavaScript 错误
  • inspect_console_object("window") - 检查任何 JavaScript 对象

✨ 主要特性

  • 网络监控：通过过滤选项捕获和分析 HTTP 请求/响应
  • 控制台集成：读取浏览器控制台日志、分析错误并执行 JavaScript
  • 性能指标：获取计时数据、资源加载情况和内存利用率
  • 页面检查：获取 DOM 信息、页面指标并支持多框架
  • 存储访问：读取 cookie、localStorage 和 sessionStorage
  • 实时监控：实时跟踪控制台输出
  • 对象检查：检查 JavaScript 对象和变量

📦 安装指南

选项 1：Claude 桌面扩展（最简单）

下载预构建的扩展：

  1. 从 Releases 下载最新的 .dxt 文件。
  2. 打开 Claude 桌面版。
  3. 转到“扩展”并安装下载的 .dxt 文件。
  4. 如果需要，在扩展设置中配置 Chrome 路径。

该扩展包含所有依赖项，可立即使用！

选项 2：MCP CLI（高级）

快速安装（最常见）：

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

注意：mcp 命令是 Python MCP SDK 的一部分。如果尚未安装，请使用 pip install mcp 进行安装。

所有安装选项：

# 克隆仓库
git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

# --with-editable 标志使用 pyproject.toml 安装依赖项

# 基本安装，使用本地依赖项
mcp install server.py --with-editable .

# 使用自定义名称安装
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

# 使用环境变量安装
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222

# 如果需要，安装额外的包
mcp install server.py -n "Chrome DevTools MCP" --with-editable . --with websockets --with aiohttp

# 使用环境文件安装（先将 .env.example 复制到 .env）
cp .env.example .env
# 使用你的设置编辑 .env
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -f .env

选项 3：Claude 代码集成

对于 Claude 代码 CLI 用户：

  1. 克隆此仓库
git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
  1. 使用 UV 安装依赖项（创建虚拟环境）
uv sync  # 创建 .venv 并安装依赖项
  1. 使用 Claude CLI 并使用绝对路径添加 MCP 服务器

重要提示：Claude 代码需要 Python 解释器和服务器脚本的绝对路径才能正常工作。

推荐使用绝对路径进行设置：

# 获取绝对路径
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"

# 使用绝对路径添加服务器
claude mcp add chrome-devtools "$PYTHON_PATH" "$SERVER_PATH" -e CHROME_DEBUG_PORT=9222

替代方法：使用系统 Python（如果依赖项已全局安装）：

# 仅当你已全局安装依赖项时使用
claude mcp add chrome-devtools python "$(pwd)/server.py" -e CHROME_DEBUG_PORT=9222

使用自定义作用域：

# 添加到用户作用域（在所有项目中可用）
claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s user -e CHROME_DEBUG_PORT=9222

# 添加到项目作用域（仅适用于此项目）
claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s project -e CHROME_DEBUG_PORT=9222
  1. 验证安装
# 列出已配置的 MCP 服务器
claude mcp list

# 获取服务器的详细信息（检查路径是否为绝对路径）
claude mcp get chrome-devtools

# 输出应显示绝对路径，例如：
# Command: /Users/you/chrome-devtools-mcp/.venv/bin/python
# Args: ["/Users/you/chrome-devtools-mcp/server.py"]

常见路径问题及解决方案：

  • 问题：“python: command not found” 或 “server.py not found”
    • 解决方案：使用上述所示的绝对路径
  • 问题：服务器启动时出现 “ModuleNotFoundError”
    • 解决方案：使用已安装依赖项的虚拟环境 Python 解释器
  • 问题：服务器未启动或显示为断开连接
    • 解决方案：手动测试命令：/path/to/.venv/bin/python /path/to/server.py

选项 4：手动进行 Claude 桌面设置

  1. 克隆此仓库
git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
  1. 安装依赖项

使用 uv（推荐）：

uv sync

使用 pip：

pip install -r requirements.txt
  1. 添加到 Claude 桌面配置

编辑你的 Claude 桌面配置文件：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"chrome-devtools": {
"command": "python",
"args": ["/absolute/path/to/chrome-devtools-mcp/server.py"],
"env": {
"CHROME_DEBUG_PORT": "9222"
}
}
}
}
  1. 重启 Claude 桌面

验证安装

安装完成后（使用任何一种方法），验证服务器是否可用：

  1. 打开 Claude 桌面版。
  2. 在对话中查找 MCP 工具。
  3. 尝试执行一个简单的命令：get_connection_status()

替代 MCP 客户端

对于其他 MCP 客户端，直接运行服务器：

python server.py

💻 使用示例

基础用法

# 一键启动 Chrome 并连接到应用程序
start_chrome_and_connect("localhost:3000")

高级用法

# 手动分步启动 Chrome、导航到应用程序并连接到浏览器
start_chrome()
navigate_to_url("localhost:3000")
connect_to_browser()

📚 详细文档

可用的 MCP 工具

Chrome 管理

  • start_chrome(port?, url?, headless?, chrome_path?, auto_connect?) - 启动具有远程调试功能的 Chrome，并可选择自动连接
  • start_chrome_and_connect(url, port?, headless?, chrome_path?) - 一步完成启动 Chrome、连接并导航到指定 URL
  • connect_to_browser(port?) - 连接到现有的 Chrome 实例
  • navigate_to_url(url) - 导航到指定的 URL
  • disconnect_from_browser() - 断开与浏览器的连接
  • get_connection_status() - 检查连接状态

网络监控

  • get_network_requests(filter_domain?, filter_status?, limit?) - 获取经过过滤的网络请求
  • get_network_response(request_id) - 获取详细的响应数据，包括响应体

控制台工具

  • get_console_logs(level?, limit?) - 获取浏览器控制台日志
  • get_console_error_summary() - 获取组织好的错误和警告摘要
  • execute_javascript(code) - 在浏览器上下文中执行 JavaScript
  • clear_console() - 清除浏览器控制台
  • inspect_console_object(expression) - 深入检查任何 JavaScript 对象
  • monitor_console_live(duration_seconds) - 实时监控控制台输出

页面分析

  • get_page_info() - 获取全面的页面指标和性能数据
  • evaluate_in_all_frames(code) - 在所有框架/iframe 中执行 JavaScript
  • get_performance_metrics() - 获取详细的性能指标和资源计时数据

存储与数据

  • get_storage_usage_and_quota(origin) - 获取存储使用情况和配额信息
  • clear_storage_for_origin(origin, storage_types?) - 按类型和来源清除存储
  • get_all_cookies() - 获取所有浏览器 cookie
  • clear_all_cookies() - 清除所有浏览器 cookie
  • set_cookie(name, value, domain, path?, expires?, http_only?, secure?, same_site?) - 设置一个 cookie
  • get_cookies(domain?) - 获取经过可选域名过滤的浏览器 cookie
  • get_storage_key_for_frame(frame_id) - 获取特定框架的存储键
  • track_cache_storage(origin, enable?) - 启用/禁用缓存存储跟踪
  • track_indexeddb(origin, enable?) - 启用/禁用 IndexedDB 跟踪
  • override_storage_quota(origin, quota_size_mb?) - 覆盖存储配额

使用案例

调试 Web 应用程序中的 API 调用

当你的 Web 应用程序进行 API 调用时，如果调用失败或返回意外数据：

简单设置：使用一步命令启动 Chrome 并导航到你的应用程序：

示例工作流程：

你：“我需要调试运行在 localhost:3000 上的 React 应用程序”
Claude：我将启动启用调试功能的 Chrome 并导航到你的应用程序。

start_chrome_and_connect("localhost:3000")

完美！Chrome 现已启动并启用调试功能，且已连接到你的应用程序。让我检查是否有失败的网络请求：

get_network_requests(filter_status=500)

我发现有 3 个请求你的 API 的请求失败了。让我获取第一个请求的详细信息：

get_network_response("request-123")

手动设置（如果你更喜欢手动操作）：

  1. 启动 Chrome：使用 start_chrome()
  2. 导航到你的应用程序：使用 navigate_to_url("localhost:3000")
  3. 连接：使用 connect_to_browser()
  4. 监控网络流量：使用 get_network_requests() 查看所有 API 调用

检查 JavaScript 控制台错误

当你的 Web 应用程序出现 JavaScript 错误或意外行为时：

  1. 在已连接的 Chrome 实例中导航到你的应用程序
  2. 检查控制台错误：使用 get_console_error_summary() 查看所有错误
  3. 监控实时错误：使用 monitor_console_live(10) 在你与应用程序交互时监控新的错误
  4. 检查变量：使用 inspect_console_object("myVariable") 检查应用程序的状态

示例工作流程：

你：“我的 React 组件更新不正常”
Claude：让我检查 JavaScript 控制台是否有错误。

get_console_error_summary()

我发现有 2 个 JavaScript 错误。让我在你与组件交互时监控控制台：

monitor_console_live(15)

现在尝试点击不正常工作的组件。我会监控是否有新的错误或警告。

性能调试

当你的 Web 应用程序加载缓慢或使用过多内存时：

  1. 在已连接的浏览器中加载你的应用程序
  2. 检查页面指标：使用 get_page_info() 查看加载时间和资源数量
  3. 分析性能：使用 get_performance_metrics() 查看详细的计时数据
  4. 监控内存使用情况：在性能指标中检查内存信息

示例工作流程：

你：“我的应用程序加载时间过长”
Claude：让我分析你的应用程序的性能。

get_page_info()

我发现你的页面有 47 个脚本，加载时间为 3.2 秒。让我获取更详细的性能数据：

get_performance_metrics()

主要的瓶颈是初始 JavaScript 包，大小为 2.1MB。DOM 处理也需要 800ms。

调试身份验证问题

当登录或会话管理出现问题时：

  1. 导航到你的登录页面
  2. 检查 cookie：使用 get_cookies() 查看身份验证 cookie
  3. 在登录过程中监控网络：在登录过程中使用 monitor_console_live() 和 get_network_requests()
  4. 检查存储的数据：使用 JavaScript 执行来检查 localStorage/sessionStorage

示例工作流程：

你：“用户无法保持登录状态”
Claude：让我检查身份验证设置。

get_cookies()

我发现身份验证 cookie 存在。让我通过监控网络来检查登录过程中发生了什么：

get_network_requests(filter_domain="your-api.com")

我注意到登录请求返回了 200 状态码，但没有 Set-Cookie 头。让我也检查一下 localStorage：

execute_javascript("Object.keys(localStorage)")

DOM 元素检查

  • get_document(depth?, pierce?) - 检索 DOM 文档结构
  • query_selector(node_id, selector) - 通过 CSS 选择器查找单个元素
  • query_selector_all(node_id, selector) - 通过 CSS 选择器查找多个元素
  • get_element_attributes(node_id) - 获取元素的所有属性
  • get_element_outer_html(node_id) - 获取元素的外部 HTML
  • get_element_box_model(node_id) - 获取元素的布局信息
  • describe_element(node_id, depth?) - 获取元素的详细描述
  • get_element_at_position(x, y) - 获取屏幕指定位置的元素
  • search_elements(query) - 通过文本/属性搜索 DOM 元素
  • focus_element(node_id) - 聚焦 DOM 元素

CSS 样式分析

  • get_computed_styles(node_id) - 获取计算后的 CSS 样式
  • get_inline_styles(node_id) - 获取内联样式
  • get_matched_styles(node_id) - 获取与元素匹配的所有 CSS 规则
  • get_stylesheet_text(stylesheet_id) - 获取样式表内容
  • get_background_colors(node_id) - 获取背景颜色和字体信息
  • get_platform_fonts(node_id) - 获取平台字体信息
  • get_media_queries() - 获取所有媒体查询
  • collect_css_class_names(stylesheet_id) - 收集 CSS 类名
  • start_css_coverage_tracking() - 开始 CSS 覆盖率跟踪
  • stop_css_coverage_tracking() - 停止并获取 CSS 覆盖率结果

常见命令

任务 命令
启动 Chrome 并连接到应用程序 start_chrome_and_connect("localhost:3000")
启动 Chrome（手动设置） start_chrome()
导航到页面 navigate_to_url("localhost:3000")
连接到浏览器 connect_to_browser()
查看所有网络请求 get_network_requests()
查找失败的 API 调用 get_network_requests(filter_status=404)
检查 JavaScript 错误 get_console_error_summary()
实时监控控制台 monitor_console_live(10)
检查页面加载性能 get_page_info()
检查变量 inspect_console_object("window.myApp")
查看 cookie get_cookies()
运行 JavaScript execute_javascript("document.title")

配置

环境变量

  • CHROME_DEBUG_PORT - Chrome 远程调试端口（默认值：9222）

MCP 兼容性

  • MCP 协议版本：2024 - 11 - 05
  • 最低 Python 版本：3.10+
  • 支持的 MCP 客户端：Claude 桌面版，任何兼容 MCP 的客户端
  • 包管理器：uv（推荐）或 pip

使用工作流程

先决条件（你的开发环境）

  • 确保你的 Web 应用程序正在运行（例如，npm run dev、python -m http.server 等）
  • 记录你的应用程序可访问的 URL

调试会话

  1. 通过 Claude 桌面版连接到你的应用程序：

    start_chrome_and_connect("localhost:3000")

    将其替换为你的应用程序的 URL

  2. 使用 MCP 工具调试你的应用程序：

    • 监控网络请求
    • 检查控制台错误
    • 检查 JavaScript 对象
    • 分析性能

  3. 在编辑器中修改你的代码

  4. 刷新或与你的应用程序进行交互

  5. 使用实时数据继续调试

手动连接（替代方法）

如果你更喜欢分步控制：

  1. start_chrome() - 启动具有调试功能的 Chrome
  2. navigate_to_url("your-app-url") - 导航到你的应用程序
  3. connect_to_browser() - 连接 MCP 服务器
  4. 根据需要使用调试工具

安全注意事项

  • 仅在开发环境中使用此工具。
  • 切勿连接到生产环境的 Chrome 实例。
  • 该服务器仅用于本地主机调试。
  • 不会永久存储任何数据，所有数据均基于会话。

故障排除

服务器在 Claude 桌面版中显示为“已禁用”

如果服务器在 Claude 中显示但显示为“已禁用”，请尝试以下步骤：

  1. 检查 Claude 桌面版日志：

    • macOS：~/Library/Logs/Claude/mcp*.log
    • Windows：%APPDATA%/Claude/logs/mcp*.log

  2. 常见修复方法：

    # 重新安装并显示详细输出
mcp remove "Chrome DevTools MCP"
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222

# 检查安装状态
mcp list

# 手动测试服务器
python3 server.py

  3. 检查依赖项：

    # 确保所有依赖项都可用
pip install mcp websockets aiohttp

# 测试导入
python3 -c "from server import mcp; print('OK')"

  4. 完全重启 Claude 桌面版（退出并重新打开）

安装问题

  • 未找到 MCP CLI：从 Python MCP SDK 安装 MCP CLI，使用 pip install mcp。
  • 服务器未在 Claude 中显示：
    • 对于 MCP CLI：运行 mcp list 以验证服务器是否已安装。
    • 对于手动设置：检查 Claude 桌面版配置文件的路径和 JSON 语法。
  • 导入错误：
    • 对于 MCP CLI：使用 --with-editable . 安装本地依赖项。
    • 对于手动设置：运行 pip install -r requirements.txt。
  • 权限错误：在配置中使用绝对路径。
  • 环境变量不起作用：验证 .env 文件的格式或 -v 标志的语法。
  • 未找到模块：确保在安装本地包时使用 --with-editable . 标志。

调试步骤

步骤 1：检查 MCP CLI 状态

# 列出所有已安装的服务器
mcp list

# 检查特定服务器的状态
mcp status "Chrome DevTools MCP"

步骤 2：手动测试服务器

# 测试服务器是否可以无错误启动
python3 server.py

# 测试导入
python3 -c "from server import mcp; print(f'Server: {mcp.name}')"

步骤 3：检查配置

对于 Claude 桌面版：

# 查看当前配置（macOS）
cat "~/Library/Application Support/Claude/claude_desktop_config.json"

# 查看当前配置（Windows）
type "%APPDATA%/Claude/claude_desktop_config.json"

对于 Claude 代码：

# 列出已配置的 MCP 服务器
claude mcp list

# 获取特定服务器的详细信息
claude mcp get chrome-devtools

# 重要提示：验证路径是否为绝对路径，而不是相对路径
# 良好的输出示例：
#   Command: /Users/you/chrome-devtools-mcp/.venv/bin/python
#   Args: ["/Users/you/chrome-devtools-mcp/server.py"]
# 不良的输出示例：
#   Command: python
#   Args: ["server.py"]

# 测试 Claude 代码将使用的精确命令
/path/to/.venv/bin/python /path/to/server.py

# 检查服务器是否正常工作
claude mcp serve --help

步骤 3.5：修复路径问题（Claude 代码特定）

# 如果路径是相对路径，请移除并使用绝对路径重新添加
claude mcp remove chrome-devtools

# 使用绝对路径重新添加
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"
claude mcp add chrome-devtools "$PYTHON_PATH" "$SERVER_PATH" -e CHROME_DEBUG_PORT=9222

步骤 4：如有需要，重新安装

对于 MCP CLI：

# 彻底重新安装
mcp remove "Chrome DevTools MCP"
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

# 完全重启 Claude 桌面版

对于 Claude 代码：

# 移除并重新添加服务器
claude mcp remove chrome-devtools
claude mcp add chrome-devtools python server.py -e CHROME_DEBUG_PORT=9222

# 或者使用不同的作用域进行更新
claude mcp add chrome-devtools python server.py -s user -e CHROME_DEBUG_PORT=9222

常见错误消息

错误 解决方案
"Module not found" 使用 --with-editable . 标志
"No server object found" 服务器应导出 mcp 对象（此问题已修复）
"Import error" 检查 pip install mcp websockets aiohttp
"Permission denied" 在配置中使用绝对路径
"Server disabled" 检查 Claude 桌面版日志，重启 Claude
"python: command not found"（Claude 代码） 使用虚拟环境 Python 的绝对路径：/path/to/.venv/bin/python
"server.py: No such file"（Claude 代码） 使用服务器的绝对路径：/path/to/server.py
"ModuleNotFoundError"（Claude 代码） 使用已安装依赖项的虚拟环境 Python

手动配置备用方案

对于 Claude 桌面版： 如果 MCP CLI 无法正常工作，请手动将以下内容添加到 Claude 桌面版配置中：

{
"mcpServers": {
"chrome-devtools": {
"command": "python3",
"args": ["/absolute/path/to/chrome-devtools-mcp/server.py"],
"env": {
"CHROME_DEBUG_PORT": "9222"
}
}
}
}

对于 Claude 代码： 如果 claude mcp add 命令无法正常工作，你可以使用带有绝对路径的 JSON 格式：

# 首先获取绝对路径
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"

# 使用带有绝对路径的 JSON 配置添加服务器
claude mcp add-json chrome-devtools "{
\"command\": \"$PYTHON_PATH\",
\"args\": [\"$SERVER_PATH\"],
\"env\": {
\"CHROME_DEBUG_PORT\": \"9222\"
}
}"

# 或者如果你在 Claude 桌面版中已配置成功，可以从那里导入
claude mcp add-from-claude-desktop

Claude 代码正确配置示例（使用绝对路径）：

{
"command": "/Users/you/chrome-devtools-mcp/.venv/bin/python",
"args": ["/Users/you/chrome-devtools-mcp/server.py"],
"env": {
"CHROME_DEBUG_PORT": "9222"
}
}

连接问题

  • Chrome 无法启动：当你使用 start_chrome() 时，MCP 服务器将自动启动 Chrome。
  • 无法连接：尝试使用 get_connection_status() 检查连接状态。
  • 工具无法正常工作：确保你已调用 connect_to_browser() 或使用了 start_chrome_and_connect()。

常见误解

  • 这不是一个 Web 服务器：MCP 服务器在 Claude 桌面版内部运行，而不是作为一个独立的 Web 服务。
  • 无需单独安装：一旦在 Claude 桌面版中配置完成，服务器将自动启动。
  • 你的应用程序独立运行：此工具用于连接到你现有的 Web 应用程序，而不是运行该应用程序。

🔧 技术细节

开发与测试

本节适用于想要测试或修改 MCP 服务器本身的开发者。

开发设置

使用 uv（推荐）：

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
uv sync

使用 pip：

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
pip install -e ".[dev]"

代码质量工具

# 格式化代码
uv run ruff format .

# 代码检查
uv run ruff check .

# 类型检查
uv run mypy src/

构建扩展

安装 DXT 打包工具：

npm install -g @anthropic-ai/dxt

构建扩展：

# 快速构建
make package

# 或者手动构建
npx @anthropic-ai/dxt pack

在开发中使用 Makefile：

make help           # 显示所有命令
make install        # 安装依赖项
make dev            # 设置开发环境并配置预提交钩子
make check          # 运行所有检查（检查、类型检查和测试）
make pre-commit     # 手动运行预提交钩子
make package        # 构建 .dxt 扩展
make release        # 完整的发布构建

预提交钩子

本项目使用预提交钩子来确保代码质量：

  • ruff：代码检查和格式化
  • mypy：类型检查
  • pytest：测试验证
  • MCP 验证：服务器注册检查

预提交钩子在 git commit 时自动运行，也可以使用 make pre-commit 手动运行。

📄 许可证

本项目采用 MIT 许可证。

默认排序 时间排序

0 个评论

« 上一篇
Wireshark
下一篇 »
K6 Mcp Server
  • 0 关注
  • 0 收藏，27 浏览
  • system 提出于 2025-10-06 11:42

相似服务问题

相关AI产品

  • 暂无相关AI产品

热议话题 »