mcp浏览器开发工具

](https://www.npmjs.com/package/mcp-browser-dev-tools) ](https://www.npmjs.com/package/mcp-browser-dev-tools)

mcp-browser-dev-tools 是一个本地MCP服务器，允许AI客户端通过Chromium DevTools协议或Firefox WebDriver BiDi检查浏览器状态。

它是为本地信任边界设计的：

AI client -> MCP over stdio -> local broker -> browser adapter -> page target

所得

用于本地桌面和终端客户端的stdio MCP服务器
Chrome、Edge、其他Chromium系列浏览器和Firefox的浏览器发现和连接/分离
选项卡生命周期工具，用于通过MCP创建和关闭浏览器选项卡
DOM查找、更丰富的元素细节、Cookie、存储、控制台消息、网络请求、类似HAR的导出、屏幕截图、标签列表和缓冲事件的检查工具
用于导航、重新加载、单击、悬停、键入、选择、按键、滚动和视口覆盖的页面交互工具
选择器可见性、URL更改和文档就绪状态的等待条件
页面状态、存储摘要、最近控制台、最近网络和屏幕截图的一次性调试包捕获
显式环境标志后面的可选JavaScript求值
助手命令，用于检查浏览器连接、启动启用调试的浏览器以及在本地机器边界上中继CDP流量

需求

Node.js 24+
本地浏览器公开CDP或BiDi，或允许代理在本地启动一个
默认情况下为环回端点；远程端点需要一个明确的选择加入标志

快速开始

在正常使用中，用户只需在代理客户端中注册此MCP服务器即可。之后，让代理通过MCP驱动浏览器。

如果您想要最简单的本地路径，请从默认路径开始 auto 设置。代理可以自动发现环回CDP和BiDi端口，通过MCP启动兼容的浏览器，并在WSL中根据配置要求引导Windows Chrome或Edge中继。

法典

codex mcp add browser-devtools -- npx -y mcp-browser-dev-tools serve

克劳德代码

claude mcp add browser-devtools --scope user -- npx -y mcp-browser-dev-tools serve

光标

{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "mcp-browser-dev-tools", "serve"]
    }
  }
}

这些命令故意不包含配置文件标志。他们只启动了MCP经纪人。浏览器启动选项属于后者 ensure_browser 或 launch_browser 代理在代理运行后进行的调用，代理可以在需要时自动创建临时Chromium系列配置文件。

安装后

服务器注册后，正常的工作流程是直接向代理请求浏览器工作：

打开指向URL的浏览器并检查页面
附加到当前选项卡并检查DOM、控制台或网络状态
截取屏幕截图或捕获调试报告

代理人通常应该从 ensure_browser该工具可以确认浏览器可用性，在需要时启动浏览器，并可选择在一个步骤中打开所请求的URL。

如果代理启动Chrome或Edge时没有 userDataDir，代理检查同一浏览器系列是否已在运行。如果是这样，代理在启动之前会自动创建一个临时配置文件目录，这样新的调试标志就不会被已经运行的配置文件吞噬。

典型的临时剖面位置：

Windows代理： %TEMP%\\mcp-browser-dev-tools-edge 或PowerShell $env:TEMP\\mcp-browser-dev-tools-edge
macOS代理： $HOME/Library/Caches/mcp-browser-dev-tools-profile
Linux或WSL代理： $HOME/.cache/mcp-browser-dev-tools-profile

使用与运行代理进程的操作系统匹配的路径。如果你想要一个稳定或可重用的配置文件路径，仍然可以通过 userDataDir 明确地。如果浏览器已打开并已公开调试端点，则代理仍可连接到它。如果Chrome或Edge已打开但没有调试端点，自动临时配置文件是通过启动的默认安全路径 ensure_browser, launch_browser，或手册 open 命令。

示例 ensure_browser Chrome或Edge的有效载荷：

{
  "browserFamily": "edge",
  "url": "https://example.com"
}

添加 userDataDir 只有当你想强制使用特定的配置文件路径时。

当代理启动浏览器时，结果会报告所选内容 userDataDir, profileStrategy，以及 existingBrowserProcess 状态，以便代理可以查看是否自动选择了临时配置文件。

MCP客户端配置

相同的启动配置文件建议适用于下面的每个MCP客户端配置：如果你以后要求代理启动Chrome或Edge，你可以通过 userDataDir 强制特定的配置文件路径，但如果省略它，则代理可以在已经运行的Chromium系列浏览器会吞下新的调试标志时自动创建临时配置文件。配置命令本身仍然只启动 serve；它们不包含浏览器启动参数。

法典

最小本地设置：

codex mcp add browser-devtools -- npx -y mcp-browser-dev-tools serve

等效 ~/.codex/config.toml 条目：

[mcp_servers.browser-devtools]
command = "npx"
args = ["-y", "mcp-browser-dev-tools", "serve"]

克劳德代码

最小本地设置：

claude mcp add browser-devtools --scope user -- npx -y mcp-browser-dev-tools serve

在本机Windows上，换行 npx 随着 cmd /c:

claude mcp add browser-devtools --scope user --env MCP_BROWSER_FAMILY=auto --env CDP_BASE_URL=http://127.0.0.1:9223 --env FIREFOX_BIDI_WS_URL=ws://127.0.0.1:9222 -- cmd /c npx -y mcp-browser-dev-tools serve

等效 .mcp.json 形状：

{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "mcp-browser-dev-tools", "serve"]
    }
  }
}

光标

最小本地设置：

{
  "mcpServers": {
    "browser-devtools": {
      "command": "npx",
      "args": ["-y", "mcp-browser-dev-tools", "serve"]
    }
  }
}

常见变体

默认代理模式为 auto。如果要将代理固定到一个浏览器系列或一组端点，请在MCP客户端配置中更改环境。

自动模式，两个浏览器连接到一个MCP服务器：

{
  "MCP_BROWSER_FAMILY": "auto",
  "CDP_BASE_URL": "http://127.0.0.1:9223",
  "FIREFOX_BIDI_WS_URL": "ws://127.0.0.1:9222"
}

火狐浏览器：

{
  "MCP_BROWSER_FAMILY": "firefox",
  "FIREFOX_BIDI_WS_URL": "ws://127.0.0.1:9222"
}

Microsoft Edge：

{
  "MCP_BROWSER_FAMILY": "edge",
  "CDP_BASE_URL": "http://127.0.0.1:9222"
}

手动将Windows浏览器中继到WSL：

{
  "MCP_BROWSER_FAMILY": "chromium",
  "MCP_BROWSER_ALLOW_REMOTE_ENDPOINTS": "1",
  "CDP_BASE_URL": "http://:9223"
}

如果您只想要一个CDP浏览器，请切换 MCP_BROWSER_FAMILY 回到 chromium 或 edge 并省略 FIREFOX_BIDI_WS_URL.

启用 evaluate_js:

{
  "MCP_BROWSER_ENABLE_EVAL": "1"
}

为启用不安全的浏览器启动参数 launch_browser 和 ensure_browser:

{
  "MCP_BROWSER_ENABLE_UNSAFE_LAUNCH_ARGS": "1"
}

如果您在Windows Chrome或Edge浏览器上使用WSL，请选择 serve --bootstrap-wsl-relay 在配置的args中，而不是手动接线 relay。如果您使用WSL的Windows Firefox，或 auto 在Windows Firefox和Windows Chrome或Edge模式下，请在Windows上运行代理。完整示例见 docs/setup.md.

高级环境选项

MCP_BROWSER_FAMILY 默认为 auto；set chromium, edge，或 firefox 将代理固定到一个浏览器系列
CDP_BASE_URL 默认为 http://127.0.0.1:9222；当保持默认值时，代理会探测环回端口 9222 通过 9226 对于可访问的CDP浏览器端点
FIREFOX_BIDI_WS_URL 默认为 ws://127.0.0.1:9222；当保持默认值时，代理会探测环回端口 9222 通过 9226，当指向根Firefox远程调试端口时，它会连接到 /session websocket并在那里创建BiDi会话
在 auto 模式下，为CDP和Firefox分配不同的端口，以便两个浏览器可以同时运行
MCP_BROWSER_EVENT_BUFFER_SIZE 设置每个会话的缓冲事件限制
MCP_BROWSER_LOG_LEVEL 控制诊断日志记录 stderr: error, warn, info，或 debug
MCP_BROWSER_DEBUG_STDIO=1 向发送原始MCP stdio传输诊断 stderr
MCP_BROWSER_ENABLE_EVAL=1 使能够 evaluate_js
MCP_BROWSER_ENABLE_UNSAFE_LAUNCH_ARGS=1 暴露 unsafeArgs 启动选项打开 launch_browser 和 ensure_browser
MCP_BROWSER_ALLOW_REMOTE_ENDPOINTS=1 允许非环回CDP或BiDi端点
MCP_BROWSER_ALLOW_REMOTE_CDP=1 仍被接受为旧别名
MCP_BROWSER_WINDOWS_NODE 可选择覆盖Windows node 可执行文件由使用 serve --bootstrap-wsl-relay
MCP_PROTOCOL_VERSION 覆盖通告的MCP协议版本

外露工具

browser_status 也返回代理元数据： serverName 和 serverVersion

在 auto 模式下还包括每个浏览器适配器的状态 browsers 协议适配器还可以包括 attemptedEndpoint 当发现重试或回退探测发生时

ensure_browser

确保兼容的浏览器可访问，必要时启动浏览器，并可以在单个MCP调用中打开所请求URL的选项卡在 auto 模式，通行证 browserFamily 对于Chrome或Edge的发布， userDataDir 是可选的；如果省略，当已经运行的浏览器进程需要时，代理会自动创建一个临时配置文件当 MCP_BROWSER_ENABLE_UNSAFE_LAUNCH_ARGS=1，此工具也接受 unsafeArgs 作为浏览器标志的数组。仍然无法覆盖代理管理的启动标志，如调试端口和配置文件路径。

launch_browser

启动与当前代理配置匹配的本地启用调试的浏览器，并可以返回内联医生报告在 auto 模式，通行证 browserFamily 对于Chrome或Edge的发布， userDataDir 是可选的；如果省略，当已经运行的浏览器进程需要时，代理会自动创建一个临时配置文件当 MCP_BROWSER_ENABLE_UNSAFE_LAUNCH_ARGS=1，此工具也接受 unsafeArgs 作为浏览器标志的数组。仍然无法覆盖代理管理的启动标志，如调试端口和配置文件路径。

list_tabs

在 auto 每种模式 targetId 名称间隔为 chromium: 或 firefox:

new_tab

在 auto 模式，通行证 browserFamily

close_tab
list_sessions

在 auto 每种模式 sessionId 以相同的方式命名

attach_tab
detach_tab
get_page_state
compare_page_state
compare_selector
get_cookies
get_storage
capture_debug_report
capture_session_snapshot
restore_session_snapshot
get_har
wait_for
navigate
reload
click
hover
type
select
press_key
scroll
set_viewport
get_console_messages
get_network_requests
get_document
inspect_element
take_screenshot
get_events

evaluate_js 默认情况下故意禁用。仅当您希望代理允许执行页面端代码时才启用它。

默认情况下，不安全的浏览器启动标志也被禁用。如果启用 MCP_BROWSER_ENABLE_UNSAFE_LAUNCH_ARGS=1，只传递完整的标志字符串，例如 --remote-allow-origins=http://localhost:9222。这无法启用 evaluate_js，它仍然不允许调用者替换代理管理的启动标志，如 --remote-debugging-port 或 --user-data-dir.

对于需要 sessionId，呼叫 attach_tab 首先，重用返回的会话。

定位器语法

交互和检查工具接受这些定位器形式：

CSS选择器，例如 #app button.primary 或 css=.modal button
可见文本查找，例如 text=Open settings
角色加上可访问的名称，例如 role=button[name="Open settings"]
可访问的名称查找，例如 name=Open settings

inspect_element 返回以布局和可访问性为中心的元数据，包括边界框、可见性标志、交互标志、可访问名称、推断角色和计算样式的子集。无效的CSS选择器现在返回显式定位器错误，而不是通用DOM故障。

屏幕截图输出

take_screenshot 返回base64图像数据和元数据，例如 mimeType, byteLength，以及 scope.通行证 selector 捕获单个元素而不是整个页面。

会话快照

get_cookies 从附加的页面上下文中返回有界的页面可见Cookie
get_storage 返回有界 localStorage 和 sessionStorage 条目，可以过滤到一个存储区域
capture_debug_report 捆绑页面状态、cookie/存储摘要、最近的控制台消息、最近的网络请求和可选的屏幕截图
capture_session_snapshot 导出有边界的页面可见Cookie以及本地和会话存储，以供以后重用
restore_session_snapshot 将捕获的快照还原到当前源上，并且可以选择先清除存储
get_har 以有界的类似HAR的JSON结构导出缓冲的网络活动
compare_page_state 和 compare_selector 比较两个附加会话之间的有界状态，这在以下情况下特别有用 auto 模式

浏览器注释

Chromium在以下位置使用标准的DevTools端点 /json/version 和 /json/list
Firefox支持需要一个直接的BiDi websocket端点
在WSL中，Linux浏览器可执行文件优先于Windows回退路径
对于Windows Chrome或Edge+WSL，更喜欢代理管理的中继路径，而不是更改浏览器的远程调试绑定

为什么不是剧作家？

Playwright仍然是确定性浏览器自动化和端到端测试的更好选择。它有一个更成熟的定位器模型、断言、等待语义、跟踪和CI故事。

mcp-browser-dev-tools 解决了一个不同的问题：

它是MCP原生的，因此AI客户端调用有界的工具表面，而不是生成和执行Playwright脚本
它可以检查已打开的浏览器选项卡或创建一个新的选项卡，然后检查当前会话状态、Cookie、登录状态、扩展、控制台和网络历史记录
它专为本地AI调试工作流而设计，包括仅环回默认值、选择加入评估和Windows到WSL中继路径
它在Chromium CDP和Firefox BiDi之间提供了一个MCP接口，而不需要AI客户端知道浏览器协议的详细信息

当你想要可复制的自动化时，使用Playwright。当您希望AI助手通过MCP检查和操纵实时浏览器会话时，请使用此项目。

调试注意事项

attach_tab 现在从性能API种子网络历史记录，所以已经加载的页面仍然显示有用的请求
控制台缓冲区包括源URL、浏览器报告它们的行和列，以及可用的堆栈帧
get_page_state 报告当前URL、标题、视口和滚动位置，而不启用 evaluate_js
代理诊断写入 stderr 所以 stdout 保留用于MCP协议流量

安全默认值

除非您选择加入，否则代理只允许环回浏览器端点
默认刀具表面为读取焦点
任意页面评估是可选的
客户端与有界MCP工具界面交互，而不是与原始浏览器协议调用交互

发展

corepack enable
pnpm install
pnpm run check
pnpm run pack:check

存储库使用 pnpm 用于本地开发和CI。最终用户安装和发布流程仍然以npm注册表为目标。

附加文档：

MCP Browser Dev Tools

快速接入

详细介绍

mcp浏览器开发工具

所得

需求

快速开始

法典

克劳德代码

光标

安装后

MCP客户端配置

法典

克劳德代码

光标

常见变体

高级环境选项

外露工具

定位器语法

屏幕截图输出

会话快照

浏览器注释

为什么不是剧作家？

调试注意事项

安全默认值

发展

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP