Browser Inspector Mcp

browser-inspector-mcp

让你的 AI 编码工具也能像你使用浏览器 DevTools 一样查看 CSS。

这是一种调试基础工具，而非测试工具——没有测试运行器，也没有通过/失败结果。在 AI 编写 CSS 之前，让它看看浏览器里实际呈现的内容——真实渲染出的类名、完整的规则层叠，以及哪条规则生效、原因是什么。数据与人类在 DevTools 中看到的一样。无需手动复制粘贴。遇到问题时，工具会解释原因，并指出可能的根源。

完整文档和示例 →

{
  "mcpServers": {
    "browser-inspector": {
      "command": "npx",
      "args": ["-y", "browser-inspector-mcp"]
    }
  }
}

node --version

此工具会在实时浏览器中检查 CSS。这意味着你需要在电脑上运行一个 Web 项目，通常是正在开发的 React、Vue 或类似应用。

在本地运行项目后，它会在类似 http://localhost:5173 或 http://localhost:3000 的地址打开。你需要把这个 URL 提供给此工具。

如果你没有本地项目，此工具就没有可供检查的内容。它是为活跃的开发工作流设计的，并非用于检查公开网站。

如何安装

你无需提前安装任何内容。配置 AI 工具（下一步）时，它会在首次需要时，通过名为 npx 的工具自动下载并运行 browser-inspector-mcp。

首次运行时，它还会下载一个名为 Chromium 的浏览器（约 170MB）。这是此工具用来检查页面的无头浏览器，会在后台隐式运行，与平时使用的 Chrome 或 Safari 无关。

如何配置 AI 工具

你需要在电脑上的某个文件中添加一小段配置，即 JSON 块。JSON 只是一种结构化文本格式。配置块如下所示：

{
  "mcpServers": {
    "browser-inspector": {
      "command": "npx",
      "args": ["-y", "browser-inspector-mcp"]
    }
  }
}

要添加到哪个文件，取决于你使用的 AI 工具。请在下方找到对应的工具。

重要： 如果配置文件中已有其他内容，你需要将配置添加进去，而不是替换现有内容。请参阅下方示例。

Claude Code

文件位置： ~/.claude.json

~ 表示你的主文件夹。在 Mac 上，它是 /Users/yourname/。该文件可能尚不存在；如果没有，请创建一个。

打开 Terminal 并运行：

open -e ~/.claude.json

这会在 TextEdit 中打开该文件。如果文件不存在，请新建一个文件并粘贴：

{
  "mcpServers": {
    "browser-inspector": {
      "command": "npx",
      "args": ["-y", "browser-inspector-mcp"]
    }
  }
}

如果文件中已有内容，请找到 "mcpServers" 部分，并在其中添加 "browser-inspector" 块。不要删除已有内容。

保存文件，然后退出并重新打开 Claude Code。

Cursor

文件位置： ~/.cursor/mcp.json（适用于你的所有项目） 或特定项目文件夹中的 .cursor/mcp.json（仅适用于该项目）

在 Cursor 中，前往：Settings → MCP——通常可以直接通过界面添加 MCP 服务，比手动编辑文件更简单。如果你更愿意编辑文件，请添加上方相同的 JSON 块。

保存后重启 Cursor。

Windsurf

文件位置： ~/.codeium/windsurf/mcp_config.json

打开文件，添加相同的 JSON 块，保存，然后重启 Windsurf。

Cline（VS Code 扩展）

在安装了 Cline 的 VS Code 中：打开 Cline 侧边栏 → 点击设置图标 → 找到“MCP Servers” → 添加一个新服务，命令设为 npx，参数设为 ["-y", "browser-inspector-mcp"]。

其他工具（Continue、OpenCode、Codex 等）

任何兼容 MCP 的工具都接受相同的配置块。找到你的工具存储 MCP 服务配置的位置，并将配置添加到那里。

如何使用

配置完成后，工具会自动可用。你无需按名称调用它们，只需描述你正在处理的内容。

开始会话： 告诉 AI 你的开发服务运行在哪个 URL：

I'm working on the dashboard at http://localhost:5173 — the button styles aren't applying correctly.

AI 会使用所需的工具。浏览器会话会在整个对话期间保持打开；你只需提及一次 URL。

AI 在后台执行的操作：

You:  "The icon in the panel header isn't picking up the brand color"

AI:   → browser_inspect(action="dom", selector=".panel-header")
        sees the real rendered class names, finds the icon is <span class="panel__header-icon">
      → browser_inspect(action="styles", selector=".panel__header-icon", properties=["color"])
        sees there's an explicit color rule on the icon overriding the parent
      → fixes the right rule, first try

无需 DevTools。无需复制粘贴。无需来回沟通。

此工具解决的问题

通常会发生什么

你让 AI 工具修复样式问题。它读取源文件、编写 CSS 修改并应用修改。你检查浏览器，问题仍然存在。AI 再次尝试，问题还是没解决。经过几轮尝试后，你自己打开 DevTools，找到实际元素，复制 HTML 并粘贴回聊天中——这时 AI 才明白它实际要处理的是什么。

手动复制粘贴这一步？这正是此工具要弥补的不足。

为什么问题会不断出现

AI 会读取源文件，而浏览器渲染出来的内容却有所不同。

Ant Design、Material UI 和 Radix 等现代组件库会在运行时生成自己的类名——这些类名在源代码中无处可寻。你的 JSX 写的是 <Menu>。浏览器渲染出来的却是 ant-dropdown-menu-item-container。AI 在源代码中找到 ant-menu-item，于是为它编写 CSS。规则根本不会生效。

还有第二个问题：即使 AI 找对了元素，也无法确认修改是否生效。CSS 是否应用了？有没有其他样式覆盖它？font-weight 本来就是粗体，还是只是看起来像粗体？没有 DevTools，每个答案都只是猜测。

这会带来三种情况

问题 1 — 读了版型，却没看成衣

一位裁缝研究西装的原始设计版型——也就是平铺的纸样。他们熟悉每一条缝线。但眼前这套西装是别人做的，而且做过修改。版型并不等于最终成衣。

这就像 AI 读取 CSS 源文件。它读的是原始版型，而浏览器渲染出来的东西已经不同。AI 不断修改错误的缝线。

检查器就是试衣间。动手之前，先看看实际做出来的是什么样。

问题 2 — 调整屋顶上的电视天线

你在后院调整电视天线。屋里有人在看画面。每次你移动天线，都会喊一声“好点了还是更差了？”，然后等对方回答。每次调整都得来回沟通一次。

这就是“推送—检查—推送”的循环。AI 做出修改。你走到浏览器前查看，再回来输入看到的情况。每一轮都要来回折腾，而且拿着天线的人和看屏幕的人之间没有直接联系。

这个工具就是那根连接线。AI 可以自行检查结果，不用你来回跑。

问题 3 — 把病治错了

医生看到一个人脸色苍白、疲惫不堪。没有检查就认定是缺铁，并按此开药。六周后，情况毫无变化。原来问题一直是甲状腺。

AI 看到截图中的文字看起来是粗体，就认定 font-weight 设得很高，并尝试覆盖它。但实际值是 400——只是文字在那个字号下渲染出来的效果如此。AI 整个过程都在解决一个根本不存在的问题。

开药之前先检查。计算后的值就是检查结果。

适用对象

使用 AI 编码工具的设计师——Cursor、Claude Code、Windsurf、Cline。你通过视觉思考并验证结果。打开 DevTools，再把 HTML 粘贴到聊天窗口，会让你突然切换上下文，打断工作节奏。这个工具可以彻底省去这一步。

希望 AI 编程搭档自行完成闭环的前端工程师——检查、修改、验证，无需你一步步说明浏览器实际渲染的内容。

使用组件库的设计系统贡献者——这类组件库的运行时类名与源代码不一致。Ant Design、Material UI、Radix、Shadcn——只要浏览器构建出的结构与 JSX 不同，都适用。

任何调试 CSS 的人——如果你曾说过“为什么这个样式没有生效？”，并希望 AI 直接查看浏览器，而不是靠猜测来回答，这个工具就是为你准备的。

可与 claude --chrome 配合使用

Anthropic 的 claude --chrome 集成可以让 Claude Code 在实时浏览器中导航、点击、填写表单和截屏。browser-inspector-mcp 则负责另一类工作：读取 CSS 层叠关系——哪个规则生效、规则来自哪里，以及样式为什么没有生效。

它们适用于不同的工作。一个不错的工作流是：先用 claude --chrome 导航到你想检查的页面状态，再用 browser-inspector-mcp 调试 CSS。两者互不替代。

工具使用哪种 Chrome？

工具会在两种模式之一运行，并自动选择：

托管模式（零配置——默认模式）。 无需任何操作，工具会在后台启动自己的无头 Chrome。非常适合检查任何公开 URL 或本地开发服务器，无需进行任何配置。视口固定为 1440×900。

附加模式（可选启用——功能更丰富）。 工具会连接到由你控制的真实可见 Chrome：使用你的实际视口和客户端路由，而且你可以登录自己的应用，让工具检查需要身份验证、具有状态的页面。这里有一点需要提前了解：

Chrome 不允许任何程序调试你的日常配置文件。 自 Chrome 136 起（这是有意实施的安全变更），除非 Chrome 同时 使用单独的配置文件目录启动，否则 --remote-debugging-port 标志会被忽略。因此，附加模式无法使用你已有标签页的主 Chrome——它会使用你只需设置一次的专用调试版 Chrome。可以把它看作另一个供你检查的 Chrome：只需在那里登录一次你的应用，之后就会保持登录状态。

只需设置一次，让它保持运行，工具就会自动连接：

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$HOME/.chrome-debug-profile"

Linux

google-chrome --remote-debugging-port=9222 --user-data-dir="$HOME/.chrome-debug-profile"

Windows

"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
  --remote-debugging-port=9222 ^
  --user-data-dir=%LOCALAPPDATA%\chrome-debug-profile

--user-data-dir 必不可少——如果不设置，Chrome 136+ 会静默忽略调试端口，工具将回退到托管模式。请使用上面这样的稳定路径（持久文件夹），不要使用 /tmp，因为它会在每次运行之间被清空，导致配置文件每次打开时都是空白。提示：为该命令创建别名，这样只需按一次键即可启动；工作时让这个 Chrome 保持打开即可。

工具会先尝试附加模式；如果调试版 Chrome 未运行，则会回退到托管模式——而且每条响应都会说明使用了哪种模式，因此你始终知道自己查看的是哪个 Chrome。

环境变量

在 AI 工具的 MCP 配置中设置这些变量（与 command 和 args 并列的 env 块中）：

一个工具，四种操作

dom — 查看浏览器实际构建的内容

在 AI 编写任何 CSS 之前，它会调用此操作。该操作会返回你指定元素的真实渲染 HTML——实际运行时类名和实际 DOM 结构。

这就像试衣间。AI 会先检查实际构建的内容，再进行修改。

styles — 查看每条 CSS 规则及其优先级

当样式更改没有生效时，此操作会返回元素完整的 CSS 层叠信息：所有匹配的规则、规则的顺序、来源（样式表和行号），以及哪些属性处于生效状态、哪些被覆盖。

它还会向上检查最多 4 层祖先元素，并返回影响布局的计算样式——溢出、尺寸和 flex 上下文。当约束不在元素本身，而是在父元素上时，这很有用。

AI 可以查看你的规则是否应用到了元素、是否有其他规则覆盖它，以及最终生效的规则具体定义在哪里。

diff — 确认更改确实已生效

比较更改前后的样式。第一次调用会保存快照。CSS 更改后进行第二次调用，即可准确查看哪些属性发生了变化以及变化幅度。如果没有任何变化，它会明确说明。

AI 据此判断修复是否生效，无需你手动检查浏览器。

screenshot — 任意元素的视觉快照

返回任意元素的裁剪截图。AI 会以内嵌方式接收图像，并能看到当前处理的内容。

在附加模式下，截图会准确呈现你看到的内容——相同的视口、相同的状态，一切都相同。在托管回退模式下，截图会在无头浏览器中以 1440×900 的分辨率渲染，因此可能与你当前窗口大小下在 Chrome 中看到的内容不同。CSS 数据操作（dom、styles、diff）在两种模式下都会返回准确的数据。

openInNewTab — 附加模式的可选修饰项

当工具附加到你的 Chrome，且你传入的 url 与任何已打开的标签页都不匹配时，默认情况下它会检查当前活动标签页并添加警告。如果你希望工具为特定 URL 打开一个新标签页——例如，你想检查某个公共网站，但不想动当前的标签页——请传入 openInNewTab: true。仅适用于附加模式；其他模式下会忽略。

要求

• Node.js 18 或更高版本 — nodejs.org
• 与 MCP 兼容的 AI 编码工具（Claude Code、Cursor、Windsurf、Cline、Continue、OpenCode、Codex 或其他工具）
• 一个正在本地运行、供你检查的 Web 项目

适用于任何 CSS 方案——已针对 Tailwind JIT、CSS Modules（Next.js）和 Emotion 进行测试。

即将推出

• 交互基元 — click、hover、type，让 AI 即使在你没有手动设置浏览器的情况下，也能访问交互状态（打开菜单、焦点环、悬停效果）。会谨慎限定范围，避免与通用浏览器自动化工具重叠。
• 实时样式注入 — AI 通过 CDP 直接向浏览器写入内容，你能立即看到更改；只有在确认结果后才会修改源文件。整个流程无需保存文件或热重载。
• Portal 和 Shadow DOM 支持 — 支持渲染在父元素之外的组件库元素（下拉菜单、模态框、工具提示）。

许可证

MIT