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 桌面扩展（最简单）

下载预构建的扩展：

从 Releases 下载最新的 .dxt 文件。
打开 Claude 桌面版。
转到“扩展”并安装下载的 .dxt 文件。
如果需要，在扩展设置中配置 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 用户：

克隆此仓库

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

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

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

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

验证安装

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

克隆此仓库

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

安装依赖项

使用 uv（推荐）：

uv sync

使用 pip：

pip install -r requirements.txt

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

重启 Claude 桌面

验证安装

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

打开 Claude 桌面版。
在对话中查找 MCP 工具。
尝试执行一个简单的命令：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")

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

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

检查 JavaScript 控制台错误

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

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

示例工作流程：

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

get_console_error_summary()

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

monitor_console_live(15)

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

性能调试

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

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

示例工作流程：

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

get_page_info()

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

get_performance_metrics()

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

调试身份验证问题

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

导航到你的登录页面
检查 cookie：使用 get_cookies() 查看身份验证 cookie
在登录过程中监控网络：在登录过程中使用 monitor_console_live() 和 get_network_requests()
检查存储的数据：使用 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

调试会话

通过 Claude 桌面版连接到你的应用程序：
```
start_chrome_and_connect("localhost:3000")
```
将其替换为你的应用程序的 URL
使用 MCP 工具调试你的应用程序：
- 监控网络请求
- 检查控制台错误
- 检查 JavaScript 对象
- 分析性能
在编辑器中修改你的代码
刷新或与你的应用程序进行交互
使用实时数据继续调试

手动连接（替代方法）

如果你更喜欢分步控制：

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

安全注意事项

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

故障排除

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

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

检查 Claude 桌面版日志：
- macOS：~/Library/Logs/Claude/mcp*.log
- Windows：%APPDATA%/Claude/logs/mcp*.log

常见修复方法：

# 重新安装并显示详细输出
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

检查依赖项：

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

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

完全重启 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 条评论
分类：开发

Chrome Devtools Mcp