Chrome Devtools Manager

chrome开发工具管理器

用于管理的命令行工具 Chrome开发工具MCP 跨多个项目。它处理启动隔离的Chrome实例、管理端口分配、检测冲突和自动配置项目。

专为同时处理多个项目并需要在每个项目中运行Chrome DevTools MCP而不发生端口冲突的开发人员而构建。

目录

• 问题
• 特性
• 需求
• 安装

- 更新 - 单文件替代方案

• 用法

- 为当前项目启动Chrome - 查看端口注册表 - 扫描项目 - 将Chrome DevTools MCP添加到项目中 - 从项目中删除Chrome DevTools MCP - 进行健康检查(--doctor) - 清理配置文件目录(--clean) - 添加自定义搜索路径

• 配置文件
• 运作原理

- 端口检测 - Chrome隔离 - 端口自动分配 - 发射防护装置

• 平台支持
• 警告和已知限制
• 故障排除
• 快速参考
• 可选：短别名
• 反馈和问题
• 许可证

问题

使用Chrome DevTools MCP和以下工具时 克劳德代码，每个项目都需要在一个唯一的调试端口上拥有自己的Chrome实例。对于两三个项目，这是可以手动管理的。一旦你杂耍了十个或更多，它就会崩溃：

• 我为哪个项目分配了哪个端口？
• 9225端口是否已被占用？
• 如何每次使用正确的标志启动Chrome？
• 如何快速将Chrome DevTools MCP添加到新项目中？

chrome-devtools-manager 只需一个命令即可解决所有这些问题。

特性

• 启动Chrome浏览器 具有适用于任何项目的正确调试端口
• 港口登记处 跟踪项目中的所有任务
• 冲突检测 当两个项目共享一个端口时，会发出警告
• 自动分配端口 将Chrome DevTools MCP添加到新项目时
• 可配置的搜索路径 因此，无论你把项目放在哪里，它都能找到它们
• 创建/更新 .mcp.json 文件自动与 jq
• 移除 chrome-devtools 从一个项目的 .mcp.json 当你不再需要它的时候
• 健康检查(--doctor) 报告过时的条目、漂移、冲突和未注册的项目，而不涉及任何内容
• 配置文件清理(--clean) 擦拭 `/tmp/chrome-

对于当前项目（或所有项目） --all)，与 --force` 同时杀死活动的Chrome实例

需求

• 操作系统： 通过WSL2访问macOS、Linux或Windows
• 外壳： bash或zsh
• 铬/铬： 已安装谷歌Chrome或Chromium
• jq： 需要 --add 和 --remove （JSON操作）
• 卷曲： 可选，但推荐。启用启动后验证（轮询Chrome DevTools协议端点以确认Chrome实际上已启动） [DEAD] 活跃度检查 --doctor。没有它，脚本仍然可以工作——这些检查会被默默地跳过。
• Node.js/npx： Chrome DevTools MCP本身需要（不是直接通过此脚本，而是由MCP服务器帮助您运行）

安装jq和curl

jq 需要 --add 和 --remove. curl 每个主要操作系统都附带了它，但如果缺少它，你可能也想安装它。

# macOS (curl is pre-installed)
brew install jq

# Ubuntu / Debian
sudo apt install jq curl

# Fedora / RHEL
sudo dnf install jq curl

安装

建议的安装路径是git clone+符号链接，因此您可以 git pull 以获取更新。

1.克隆存储库

git clone https://github.com/clizaola/chrome-devtools-manager.git ~/Code/chrome-devtools-manager

（你可以在任何地方克隆它-- ~/Code/chrome-devtools-manager 这只是一个惯例。)

2.将脚本符号链接到您的 PATH

mkdir -p ~/.local/bin
ln -s ~/Code/chrome-devtools-manager/chrome-devtools-manager.sh ~/.local/bin/chrome-devtools-manager

使用符号链接意味着 git pull 自动更新命令，无需重新安装步骤。

3.添加 ~/.local/bin 到你的 PATH （如果还没有）

将此行添加到您的 ~/.zshrc 或 ~/.bashrc:

export PATH="$HOME/.local/bin:$PATH"

然后重新加载shell：

source ~/.zshrc   # or source ~/.bashrc

4.验证安装

chrome-devtools-manager --help

更新

cd ~/Code/chrome-devtools-manager
git pull

符号链接指向git工作树中的脚本，因此 git pull 这就是你所需要的——无需重新安装。

单文件替代方案

如果你不想克隆一个repo，你可以直接从GitHub获取脚本：

mkdir -p ~/.local/bin
curl -o ~/.local/bin/chrome-devtools-manager \
  https://raw.githubusercontent.com/clizaola/chrome-devtools-manager/main/chrome-devtools-manager.sh
chmod +x ~/.local/bin/chrome-devtools-manager

权衡：更新需要重新运行 curl 命令而不是 git pull.

用法

为当前项目启动Chrome

cd ~/projects/my-app
chrome-devtools-manager
# => Launching Chrome for 'my-app' on port 9222...

这将从项目的端口读取 .mcp.json 并启动一个具有自己用户配置文件的独立Chrome实例。每个项目都有完全独立的Cookie、会话和状态。

发射器还：

• 拒绝发射 如果Chrome进程已在其他端口上为此项目的配置文件目录运行。否则，Chrome的配置文件单例将默认忽略新的 --remote-debugging-port 标记并重用旧端口上的现有会话，这样启动器就会快速失败并打印出准确的会话 pkill 清除过时实例的命令。
• 验证Chrome是否实际绑定了端口 通过投票启动后 `http://127.0.0.1:

/json/version` 持续时间长达5秒。如果端点没有响应，您将收到警告，而不是无声的失败。

查看端口注册表

chrome-devtools-manager --list

输出：

Chrome DevTools MCP Port Registry
===================================
PROJECT                        PORT     PATH
-------                        ----     ----
my-app                         9222     ~/projects/my-app
api-service                    9223     ~/projects/api-service
admin-panel                    9224     ~/Code/client/admin-panel

Last scanned: 2026-03-07 10:15:33
Next available port: 9225

扫描项目

扫描所有配置的搜索路径并重建注册表：

chrome-devtools-manager --scan

输出：

Scanning for Chrome DevTools MCP configurations...
  ~/Herd/*
  ~/Herd/*/*
  ~/Code/*
  ~/Code/*/*

Chrome DevTools MCP Port Registry
===================================
PROJECT                        PORT     PATH
-------                        ----     ----
my-app                         9222     ~/projects/my-app
api-service                    9223     ~/projects/api-service

!! CONFLICT: my-app, another-app both use port 9222

Last scanned: 2026-03-07 10:20:00
Next available port: 9224

Registry saved to ~/.chrome-devtools-manager

冲突标记为 !! CONFLICT 这样你就可以立即修复它们。

将Chrome DevTools MCP添加到项目中

导航到项目文件夹并运行：

cd ~/projects/new-project

# Auto-assign the next available port
chrome-devtools-manager --add

# Or specify a port manually
chrome-devtools-manager --add 9225

这将执行以下操作：

1. 如果 .mcp.json 存在： 添加 chrome-devtools 进入现有 mcpServers 对象，保留所有其他MCP服务器
2. 如果 .mcp.json 不存在： 创建新 .mcp.json 使用chrome devtools配置
3. 检查冲突： 拒绝分配已在使用的端口
4. 自动扫描： 添加后更新注册表

生成的 .mcp.json 条目看起来像这样：

{
    "mcpServers": {
        "chrome-devtools": {
            "command": "npx",
            "args": [
                "-y",
                "chrome-devtools-mcp@latest",
                "--browserUrl",
                "http://127.0.0.1:9225"
            ]
        }
    }
}

从项目中删除Chrome DevTools MCP

当你不再想要 chrome-devtools 在一个项目的 .mcp.json，导航到项目并运行：

cd ~/projects/old-project
chrome-devtools-manager --remove

这只会删除 chrome-devtools 进入 mcpServers，保留所有其他MCP服务器。注册表会自动重新扫描，从而释放项目的端口以供重用。需要 jq.

进行健康检查(--doctor)

chrome-devtools-manager --doctor

A. 无损的 检查当前注册表和您的 .mcp.json 记录并报告它发现的任何问题。它不会修改任何文件或注册表——您可以决定修复什么。当感觉有些不对劲（缺少项目、端口错误、冲突），并且在决定运行什么之前需要快速的健康报告时，这很有用。

它报告说：

• [STALE] --项目目录不见了，或者 .mcp.json 不再包含 chrome-devtools
• [DRIFT] --港口在 .mcp.json 不再与注册表中的端口匹配（外部编辑了文件）
• [WARN] --一个项目的 chrome-devtools 条目使用的主机不是 127.0.0.1 或 localhost，因此无法检测到其端口
• [CONFLICT] --两个或多个项目共享同一端口
• [WRONG-PORT] --Chrome实例正在使用此项目的配置文件目录运行，但端口与 .mcp.json 欲望。当Chrome启动后配置的端口发生变化时，就会发生这种情况；Chrome的配置文件单例默默地重用旧会话。修复方法是终止Chrome进程并重新启动。
• [DEAD] --信息。已注册的项目，其配置的端口当前未在侦听。这对于你没有积极使用的项目来说是正常的。不算问题。
• [ORPHAN] --磁盘上的项目具有 chrome-devtools 在其 .mcp.json 但不在注册表中（run --scan 把它捡起来）

输出示例：

Chrome DevTools MCP Doctor
===========================

Checking registered projects...
  [CONFLICT] port 9229 used by: cafali,omniguard360

Scanning search paths for unregistered projects...
  [ORPHAN]   new-project at ~/Code/new-project (not in registry)

Found 2 issue(s).

Suggested actions:
  chrome-devtools-manager --scan                              Rebuild registry from disk (fixes STALE, DRIFT, ORPHAN)
  cd 
 && chrome-devtools-manager --remove            Drop a stale/unwanted entry
  cd 
 && chrome-devtools-manager --remove && chrome-devtools-manager --add   Reassign a conflicting port

清理配置文件目录(--clean)

每个项目的Chrome配置文件都在 /tmp/chrome- / 并且可以随着时间的推移而变得非常大——浏览器缓存、服务工作者、IndexedDB等。一个项目在大量使用后很容易达到多GB。重新启动时会清除温度配置文件，但 --clean 允许您释放磁盘空间或重置行为异常的浏览器状态，而无需重新启动。

默认情况下， --clean 仅涉及当前项目的简介。 使用 --all 如果你想一次清理每个项目。

# Clean ONLY the current project's profile (/tmp/chrome-)
cd ~/Code/myproject
chrome-devtools-manager --clean

# Clean the current project's profile AND kill it first if it's running
chrome-devtools-manager --clean --force

# Clean every /tmp/chrome-* profile. Skips any Chrome that is currently running.
chrome-devtools-manager --clean --all

# Nuclear: kill every running Chrome and wipe every profile
chrome-devtools-manager --clean --all --force

输出示例(--clean --all):

Scanning /tmp/ for Chrome profile directories...

  [CLEAN]      cafali (246M)
  [CLEAN]      greenmedinfo (270M)
  [SKIP]       gumplayfactory (active on port 9234, 902M)
  [CLEAN]      homer (4.3G)
  [CLEAN]      kozmetik (5.3G)

Cleaned 4 profile(s), skipped 1.

To also kill active Chrome instances and clean their profiles, add --force.

安全默认值：

• --clean 没有 --all 只有触摸 /tmp/chrome-当你只想重置一个项目时，爆炸半径要小得多。
• --clean 没有 --force 永远不会杀死正在运行的Chrome。活动配置文件报告为 [SKIP] 独自留下。
• 使用 --force 仅当您确定要终止Chrome窗口时。

注： MCP屏幕截图和快照通过MCP协议传输——它们是 不 存储在这些配置文件目录中。您看到的大小是您在调试窗口中进行的任何浏览的正常Chrome浏览器状态（缓存、Cookie、本地存储等）。清理只会让您退出该配置文件中的网站；与MCP相关的任何东西都没有丢失。

添加自定义搜索路径

默认情况下，该工具在这些目录中搜索 .mcp.json 文件夹：

~/Herd/*
~/Herd/*/*
~/Code/*
~/Code/*/*

添加您自己的：

# Single level deep
chrome-devtools-manager --path "~/Projects/*"

# Nested (e.g. org/project structure)
chrome-devtools-manager --path "~/Work/*/*"

搜索路径保存在配置文件中，并由以下人员使用 --scan.

配置文件

配置和注册表位于 ~/.chrome-devtools-manager。这是一个纯文本文件，有两个部分：

# Chrome DevTools MCP Port Registry
# https://github.com/ChromeDevTools/chrome-devtools-mcp
#
# SEARCH PATHS (add your project directories here)
~/Herd/*
~/Herd/*/*
~/Code/*
~/Code/*/*
#
# REGISTRY (auto-generated by chrome-devtools-manager --scan)
# Last scanned: 2026-03-07 10:15:33
# PROJECT|PORT|PATH
my-app|9222|~/projects/my-app
api-service|9223|~/projects/api-service

• 搜索路径部分： 您可以手动编辑此内容以添加/删除搜索目录
• 注册部分： 自动生成 --scan.不要手动编辑；每次扫描都会覆盖它

运作原理

端口检测

该工具通过扫描找到端口 .mcp.json 图案的文件 127.0.0.1: 或 localhost: 。它不会为此解析JSON；它使用了一个简单的 grep 图案。这意味着无论JSON的格式或缩进方式如何，它都能正常工作。

Chrome隔离

启动Chrome时，有两个标志可确保完全隔离：

• `--remote-debugging-port=

`：Chrome DevTools MCP连接到的调试端口

• `--user-data-dir=/tmp/chrome-

`：每个项目都有单独的Chrome配置文件

这意味着每个项目都有自己的：

• Cookie和会话
• 浏览器历史
• 扩展
• 本地存储
• 缓存

端口自动分配

当使用 --add 在不指定端口的情况下，该工具读取注册表，找到正在使用的最高端口，并分配下一个端口。起始端口为 9222 （Chrome DevTools协议默认值）。

发射防护装置

每 chrome-devtools-manager 发射会经过两次安全检查，以防止无声故障：

1. 单打后卫（发射前）。 该工具使用以下命令检查正在运行的进程列表 ps 并查找任何已在使用的Chrome主进程 `--user-data-dir=/tmp/chrome-

.如果找到一个： - **同端口 .mcp.json:** 现有会话正常，无需执行任何操作。该工具验证CDP端点是否仍在响应，并返回成功。 - **不同端口：** 该工具拒绝启动并打印出准确的 pkill` 清除过时实例的命令。这一点至关重要，因为否则Chrome会默默地忽略新的端口标志，并将启动重定向到现有会话中（这种行为过去会导致令人困惑的“MCP无法连接”错误）。

1. CDP验证（启动后）。 在生成Chrome后，该工具进行民意调查 `http://127.0.0.1:

/json/version 通过 curl 最多20次（约5秒）。如果端点响应，您将收到一条确认消息。如果没有，你会得到一个警告，指向 --doctor 和 pkill`，所以你知道发射实际上并没有生效。

这两种检查都可以通过以下方式观察到 --doctor，它使用相同的底层助手，并报告任何不一致之处 [WRONG-PORT] 或 [DEAD].

平台支持

该脚本会自动检测您的操作系统，并找到正确的Chrome/Chromium可执行文件。无需手动配置。

macOS

开箱即用。在以下位置检测Chrome：

/Applications/Google Chrome.app/Contents/MacOS/Google Chrome

Linux

按以下顺序自动检测第一个可用的可执行文件：

1. google-chrome
2. google-chrome-stable
3. chromium-browser
4. chromium

Windows（通过WSL2）

在WSL2（Linux的Windows子系统）下工作。该脚本会自动检测WSL2，并在以下位置启动Windows Chrome安装：

/mnt/c/Program Files/Google/Chrome/Application/chrome.exe

重要提示： WSL2支持尚未经过广泛测试。它应该有效，但如果你遇到问题，请报告（见下面的反馈部分）。

不支持本机Windows（PowerShell/CMD）。 该脚本需要与bash兼容的shell。

警告和已知限制

1. Chrome必须尚未运行 --user-data-dir: 如果Chrome已经正常打开，启动新实例需要 --user-data-dir 创建单独的配置文件。该工具始终使用 --user-data-dir，所以这是自动处理的。

1. 重新启动时清除温度配置文件： 用户配置文件存储在 `/tmp/chrome-

，大多数系统在重新启动时都会清除。这是有意的——它保持配置文件整洁，并自动回收磁盘空间。如果你需要持久会话（保持登录等），你需要编辑脚本以指向 --user-data-dir 在永久位置（例如。 ~/.chrome-devtools/ ).如果你这样做，记得更新 clean_profiles 功能也如此 --clean` 仍然可以找到它们。

1. 端口检测是基于grep的： 该工具搜索 `127.0.0.1:

或 localhost: 在 .mcp.json.其他主机名（例如。 0.0.0.0`，自定义域）将不会被检测到。

1. 每个端口一个 .mcp.json: 该工具仅读取每个中的第一个匹配的主机：端口对 .mcp.json。如果您在同一文件中有多个使用不同端口的MCP服务器，则只会跟踪第一个。

1. 搜索路径使用glob模式： 路径如 ~/Code/* 只匹配一级深。使用 ~/Code/*/* 对于嵌套目录。该工具不会无限重复；您必须明确指定深度。

1. --add 和 --remove 需要 jq: 这些命令使用 jq 安全地修改JSON文件。所有其他命令(--list, --scan, --doctor, --clean，启动）无需工作 jq.

1. Chrome路径自动检测： 该脚本在macOS、Linux和WSL2上自动检测Chrome。如果Chrome安装在非标准位置，您可能需要更新 get_chrome_path() 脚本中的函数。

1. WSL2支持未经测试： WSL2检测（通过 /proc/version)Windows Chrome路径应该可以工作，但尚未经过广泛测试。如果您遇到问题，请报告。

故障排除

从这里开始： --doctor

几乎每一个问题都可以在一个步骤中诊断出来：

chrome-devtools-manager --doctor

这种非破坏性检查将告诉您哪个项目有过时的条目、端口冲突、错误的端口、死侦听器或未注册的项目。每个发现都有一个建议的修复命令。如果 --doctor 报告没有问题，工具本身是健康的，问题在其他地方。

No chrome-devtools port found in .mcp.json

发射器发现了一个 .mcp.json 但没有 127.0.0.1: 或 localhost: 里面的图案。要么：

• chrome-devtools 文件中还没有→ run chrome-devtools-manager --add
• URL使用了工具无法检测到的主机（例如。 0.0.0.0，自定义主机名）→ edit .mcp.json 使用 127.0.0.1 或 localhost

MCP客户表示 `Failed to fetch browser webSocket URL from http://127.0.0.1:

/json/version: fetch failed`

MCP客户端无法在配置的端口上访问Chrome。这意味着Chrome实际上并没有在那里监听。运行：

chrome-devtools-manager --doctor

如果医生出现 [DEAD] 对于该项目，只需启动Chrome即可：

cd /path/to/project
chrome-devtools-manager

如果医生出现 [WRONG-PORT]，请参阅下一节。

[WRONG-PORT] 或 `Error: Chrome is already running for '

' on port X, but .mcp.json is configured for port Y`

当Chrome已经运行后，项目的端口发生变化时，这是最常见的陷阱。启动器现在可以明确地捕获它，但底层行为值得理解。

根本原因： Chrome具有“配置文件单例”行为。如果你启动第二个Chrome进程，指向 --user-data-dir 另一个Chrome进程Chrome已经在使用它 默默地忽略新 --remote-debugging-port 旗帜 并在现有会话中打开一个新窗口。旧港口仍然被束缚着；新港口永远不会来。

当发生以下情况时，会发生这种情况：

• 您重新分配了项目的端口（通过 --remove + --add 或通过编辑 .mcp.json)在Chrome已经为该项目推出之后
• 另一个工具（Herd、IDE集成等）重写 .mcp.json 并在Chrome仍在运行时更改了端口
• 崩溃的Chrome浏览器将其配置文件锁定状态抛在脑后

修复： 终止该特定配置文件的过时Chrome进程，然后重新启动。启动器现在检测到这种情况并打印出确切的命令，但在这里是手动的：

pkill -f "user-data-dir=/tmp/chrome-
"
cd /path/to/project
chrome-devtools-manager

这只会杀死持有一个特定配置文件目录的Chrome实例——您的其他Chrome窗口不会受到影响。

Chrome launched but port is not responding after ~5s

启动器启动了Chrome，但CDP端点从未出现。可能性：

1. Chrome在启动时崩溃（罕见；尝试手动启动一次）
2. 另一个进程是保持端口(`lsof -iTCP:

-sTCP:LISTEN`)

1. 在Chrome完成启动之前，你过快地关闭了启动器
2. 配置文件单例冲突隐藏了端口（run --doctor)

Opening in existing browser session.

Chrome会自己打印出来——这意味着配置文件单例刚刚将您的启动重定向到已经运行的Chrome中。新的 --remote-debugging-port 旗帜被忽略了。修复方法与 [WRONG-PORT] 上面。

`/tmp/chrome-

` 是巨大的

这很正常——Chrome会积极缓存web内容（HTTP缓存、服务工作者缓存、IndexedDB）。一个浏览量很大的项目很容易增长到多GB。MCP屏幕截图和快照 不 存储在这里；它们直接通过MCP协议到达客户端。

回收空间：

# Clean just the current project
cd /path/to/project
chrome-devtools-manager --clean

# Or wipe everything
chrome-devtools-manager --clean --all

cafali,omniguard360 both use port 9229 （或类似冲突）

两个项目被分配了相同的端口。选择一个进行移动：

cd /path/to/project-to-move
chrome-devtools-manager --remove
chrome-devtools-manager --add          # auto-assigns next free port

过时的条目 --list 对于您删除的项目

chrome-devtools-manager --scan

--scan 从磁盘重建注册表，因此不再存在的项目会自动退出。

快速参考

核心

项目配置

注册表

诊断和清理

可选：短别名

如果 chrome-devtools-manager 太长，无法键入，请为您的 ~/.zshrc 或 ~/.bashrc:

alias cdm='chrome-devtools-manager'

然后，您可以对每个命令使用较短的形式：

cdm                 # launch Chrome for current project
cdm --list          # show port registry
cdm --doctor        # run a health check
cdm --add           # add chrome-devtools to current project
cdm --remove        # remove chrome-devtools from current project
cdm --clean         # clean current project's profile dir

反馈和问题

• 报告问题：
• 电子邮件：support@cafali.com
• Chrome DevTools MCP：

许可证

麻省理工学院——见 许可证 全文。