browser-inspector-mcp

让你的 AI 编码工具拥有与浏览器 DevTools 相同的 CSS 可见性。

在 AI 编写 CSS 之前，让它看到浏览器中实际渲染的内容——真实的渲染类名、完整的规则层叠、生效的规则及其原因。获取人类从 DevTools 中看到的相同数据。无需手动复制粘贴。

完整文档与演示 →

要求： Node.js 18+，支持 MCP 的 AI 工具（Claude Code, Cursor, Windsurf, Cline 等），以及正在运行的本地开发服务器。

配置（添加到你的 AI 工具的 MCP 配置文件中）：

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

配置文件位置：

• Claude Code: ~/.claude.json

• Cursor: ~/.cursor/mcp.json 或 .cursor/mcp.json

• Windsurf: ~/.codeium/windsurf/mcp_config.json

• 其他：你的工具读取 MCP 服务器配置的位置

重启你的 AI 工具。首次调用时，告诉 AI 你的开发服务器运行在哪个 URL 上——浏览器会话将在对话的剩余部分保持持久。

一个工具，四个动作：browser_inspect 配合 action: "dom"（渲染后的 DOM）、"styles"（完整的 CSS 层叠）、"diff"（变更前后的验证）、"screenshot"（视觉快照）。或者直接描述你的需求——Claude 会选择正确的动作。

首次使用时，Puppeteer 会下载 Chromium（约 170MB）。

开始之前 — 你需要准备什么

此工具连接了你已经设置好的两样东西：AI 编码工具和你正在开发的 Web 项目。以下是它们的含义以及如何获取它们。

1. Node.js（运行此工具的引擎）

Node.js 是一个让你的电脑在浏览器之外运行 JavaScript 的程序。npm 和 npx（用于安装和运行此工具的命令）随 Node.js 一起提供。

你已经安装了吗？ 打开终端（Mac）或命令提示符（Windows）并输入：

node --version

如果你看到类似 v20.11.0 的版本号，那就没问题。如果报错，你需要安装它。

安装它： 从 nodejs.org 下载——获取 LTS 版本（标记为“推荐给大多数用户”的版本）。运行安装程序即可。

2. AI 编码工具

这是你向 AI 提问以编写或修复代码时使用的工具。此 MCP 服务器适用于以下任何一种——你只需要其中一个：

如果你还没有，且不知道从哪里开始：试试 Cursor。如果你有设计背景，它的学习曲线最平缓。

3. 什么是 MCP（一句话解释）

MCP (Model Context Protocol) 是一种让 AI 工具访问额外功能（如浏览器、数据库或文件系统）的标准方式。此工具就是其中一种功能。你只需在 AI 工具的配置文件中添加几行配置即可安装，它会自动出现在 AI 的工具箱中。

4. 本地运行的 Web 项目

此工具在实时浏览器中检查 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/你的名字/。该文件可能还不存在——如果不存在，请创建一个。

打开终端并运行：

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 中，转到：设置 → MCP ——通常有一个 UI 可以直接添加 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。两者互不替代。

一个工具，四个动作

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

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

这是试衣间。AI 在动手之前检查实际构建的内容。

styles — 查看每一条 CSS 规则以及谁在生效

当样式更改未显示时，此动作返回元素的完整 CSS 层叠：每一条匹配的规则、顺序、来源（样式表 + 行号），以及哪些属性是活动的，哪些是被覆盖的。

还会向上遍历最多 4 层祖先元素，并返回它们对布局至关重要的计算样式——溢出、尺寸、Flex 上下文。当约束不在元素本身而在父元素上时非常有用。

AI 可以看到你的规则是否到达了元素，是否有东西覆盖了它，以及生效的规则到底定义在哪里。

diff — 确认更改确实生效

变更前后的样式比较。第一次调用保存快照。第二次调用（在 CSS 更改后）准确显示哪些属性发生了变化以及变化幅度。如果没有变化，它会明确说明。

这就是 AI 在无需你手动检查浏览器的情况下知道其修复是否有效的方法。

screenshot — 任何元素的视觉快照

返回任何元素的裁剪截图。AI 会在对话中收到图像，并能看到它正在处理的内容。

关于截图准确性的说明： 截图是在无头浏览器中以 1440×900 分辨率渲染的。如果你的应用有响应式断点，截图可能与你在当前窗口大小下看到的浏览器内容不匹配。CSS 数据动作（dom, styles, diff）不受影响——无论视口如何，它们都会返回准确的数据。

要求

• Node.js 18 或更高版本 — nodejs.org

• 支持 MCP 的 AI 编码工具（Claude Code, Cursor, Windsurf, Cline, Continue, OpenCode, Codex 或其他任何工具）

• 你想要检查的本地运行的 Web 项目

未来计划

• 实时样式注入 — AI 通过 CDP 直接写入浏览器，你立即看到更改，只有在结果确认后才会触及源文件。循环中无需保存文件或热重载。

• 浏览器扩展移交 — 在浏览器中拖动矩形框选任何元素，它会将视觉 + DOM + 计算样式直接发送到你的 AI 会话中。一个手势完全取代手动复制粘贴。

• Portal 和 Shadow DOM 支持 — 在父元素之外渲染的组件库元素（下拉菜单、模态框、工具提示）。

许可证

MIT