Chrome Devtools MCP

🚀 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

2. 使用 UV 安装依赖项（创建虚拟环境）

uv sync  # 创建 .venv 并安装依赖项

3. 使用 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

4. 验证安装

# 列出已配置的 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

2. 安装依赖项

使用 uv（推荐）：

uv sync

使用 pip：

pip install -r requirements.txt

3. 添加到 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"
      }
    }
  }
}

4. 重启 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 许可证。