chrome-mcp

MCP 浏览器扩展

网站和文档： mcp-browser-extension.com · 快速入门 · 全部 43 个工具 · 从 Chrome 网上应用店安装扩展程序

让 Claude 使用你已经登录的 Chrome。 不用每次打开网站都像陌生访客一样的全新自动化浏览器，而是使用你的 Chrome，保留你的会话、Cookie，并且已经完成双重身份验证。只要你能在浏览器中看到某个页面，Agent 就能读取它，无需重新登录，也无需在任何地方粘贴凭据。

大多数浏览器 MCP 服务会启动自己的 Chromium，并向 Agent 提供一个未登录的窗口。MCP 浏览器扩展则相反：一个 MV3 扩展会连接到本地主机 WebSocket 服务，并通过 chrome.scripting/chrome.tabs 操控你已经打开的浏览器。可与 Claude Code、Claude Desktop 及任何其他 MCP 主机搭配使用。

MCP 浏览器扩展由两部分组成：扩展程序，以及通过 npx 运行的轻量级 MCP 服务（npm 包和命令：mcp-browser-extension）。扩展程序可从 Chrome 网上应用店 安装，也可以解压后加载。

此版本仅包含扩展程序。 它绝不会启动或连接到自己的 Chromium，因此扩展程序是必需的，而非可选项——没有扩展程序，任何工具都无法运行。CDP 标志（--cdp-fallback、--no-cdp-fallback、--cdp-endpoint、--prefer）仍可接受，以保持向后兼容，但会被忽略。

完整设计： docs/BLUEPRINT.md — 架构、线路协议、完整工具集、扩展程序清单、安全模型和分阶段构建计划。

在已登录的 Chrome 中使用 Claude

你已经登录了 Gmail、GitHub、分析仪表板、管理面板和 CRM。MCP Browser Extension 让 Claude（Claude Code、Claude Desktop 或任何其他 MCP 主机）在这些相同的标签页中工作：无需重新登录，无需再次进行双重身份验证，也无需在配置文件中保存密码或 Cookie。扩展在你日常使用的 Chrome 中运行，因此 Agent 打开的页面，就是你会看到的页面。

• Gmail — 在已打开的标签页中读取邮件会话或搜索结果。
• GitHub — 以你的身份浏览 PR、问题和设置页面，包括私有仓库。
• 仪表板 — 从没有 API 或你从未配置过 API 的分析、账单或管理界面中提取数据。

其他工具也可以驱动已登录的 Chrome（例如 hangwin/mcp-chrome 扩展），因此关键在于，除了会话之外你还能获得什么：

• 按域名设置允许列表，默认拒绝所有访问。 不设置任何标志时，Agent 无法读取任何内容。--allow-domain mail.google.com --allow-domain github.com 只开放这些主机（*.example.com 覆盖一个域及其子域）；其他所有网站都会在调用到达页面之前被拒绝。读取操作也受限，而不仅仅是点击操作；扩展还会在自身侧重新检查同一策略。修改、执行代码、下载和上传都需要单独选择启用。
• 绝不返回密码值，并且 --redact 会从页面读取内容中清除令牌、API 密钥和 JWT。
• 审计记录：每次调用都会记录 URL、允许／拒绝判定、耗时和返回的字节数。
• Chrome 中的近期活动：弹出窗口会显示最近 5 条活动（一个标签页的打开／关闭记录共用一行）；设置页面最多显示 100 条，并支持按结果筛选。此会话历史会包含网站名称和应用密钥，但不包含页面文本、输入值或完整 URL。
• 停止访问：可通过弹出窗口或设置页面断开所有应用的连接。停止状态会在重启后保留；恢复连接需要为每个应用重新批准。已在运行的命令可能会完成，已完成的操作无法撤销。
• 不会打扰你当前的标签页：Agent 会在后台打开自己的标签页并在那里操作，因此不会切换你当前所在的页面、点击其中的内容，也不会让它失去焦点。batch 可在一次调用中同时读取多个标签页。
• 多个 Chrome 配置文件：在工作和个人配置文件中加载扩展，并使用 profile_use 在它们之间切换。
• auth_check：会话过期时，Agent 会收到 [AUTH_REQUIRED] 信号，而不是令人困惑的超时，这样它就能停止操作并请你重新登录。MCP Browser Extension 不会保存凭据，也不会代你登录。

设置分为两部分：MCP 服务（下方的 npx）和扩展。你可以**从 Chrome 网上应用店安装**，也可以从服务解压出的文件夹中加载扩展。

快速开始

粘贴一次即可启动

将以下内容交给你的 AI Agent（Claude Code、Cursor、Windsurf 或任何 MCP 工具），它会安装服务、将其接入客户端，并引导你安装扩展、验证邮箱和配对 Chrome：

Set up MCP Browser Extension on this machine by fetching and following
https://raw.githubusercontent.com/Mehmoodqureshi/mcp-browser-extension/main/SETUP.md
exactly, step by step. Work autonomously and verify each step.

想在让 Agent 操作你的电脑之前先阅读说明？SETUP.md 是 Agent 会遵循的准确文件。手动步骤如下。

1. 注册 MCP 服务到你的主机。

claude mcp add mcp-browser-extension -s user -- \
  npx -y mcp-browser-extension@latest \
  --allow-domain example.com --enable-mutations --persist-token

{
  "mcpServers": {
    "mcp-browser-extension": {
      "command": "npx",
      "args": ["-y", "mcp-browser-extension@latest",
               "--allow-domain", "example.com", "--enable-mutations",
               "--persist-token"]
    }
  }
}

默认情况下，所有权限均为拒绝（不允许任何域名、代码求值或变更）。使用 --allow-domain <glob>（可重复指定）、--enable-mutations、--enable-downloads、--enable-uploads 或 --unsafe-enable-eval，仅授予所需权限。不支持访问所有网站；请在 Chrome 扩展弹出窗口中批准指定网站。

默认启用邮箱验证。对于可信的本地无人值守配置，可使用 --no-email-verification 退出验证（或设置 MCP_BROWSER_EXTENSION_EMAIL_VERIFICATION=0）。这样会跳过邮箱提示和 Firebase 访问服务，因此不会向其发送邮箱或设备授权。本地 MCP 客户端仍需在 Chrome 中获得批准，才能使用扩展，并且仍受配置的域名和功能策略限制。请将所有能够启动或访问此本地服务的进程视为可信进程。此选项不能与 --tunnel 同时使用，也不会关闭遥测或 npm 更新检查。

--enable-uploads 允许使用 upload_file（在页面的文件 <input> 中设置本地文件）。此功能默认关闭，因为向页面发送本地文件存在数据泄露风险；同时还受目标域名允许列表限制。搭配 --uploads-dir <path> 使用可将上传范围限制在该目录中的文件（会阻止 .. 路径遍历）——强烈建议在无人值守时使用。

重启后保持传输配对状态。 上述两个示例都包含 --persist-token，它能让配对状态在重启后保留；如果你更倾向于使用下文所述的更严格默认设置，可以移除它。

不使用 --persist-token 时，每次启动都会生成新令牌（安全默认设置），这意味着每次重启后都需要重新配对扩展。使用该选项后，令牌会以 0600 权限存储在 ~/.mcp-browser-extension/token 中，并在后续启动时复用；扩展的 keepalive 会自动重新连接，无需手动操作。MCP_BROWSER_EXTENSION_TOKEN 可用于显式固定令牌（且绝不会写入磁盘）。此传输配对不会授予应用访问权限：每个新应用会话都有独立密钥，并且需要在 Chrome 中获得批准。

2. 安装扩展——必需；没有扩展，服务无法执行任何操作。

从 Chrome 网上应用店安装 MCP Browser Extension。 一键安装，无需启用开发者模式，而且 Chrome 会为你自动更新。请通过此方式安装。

3. 验证邮箱。 在 MCP 客户端中，让 Agent 调用 chrome_status。首次调用浏览器工具时，客户端会显示邮箱提示。输入你可以访问的邮箱地址，然后打开发送到该地址的登录链接，并点击验证此设备。等待中的工具会报告邮箱已验证，然后继续执行。

如果工具返回 ACCESS_PENDING，让 Agent 再次调用 chrome_status，继续等待同一个链接即可。无需再次输入邮箱，也无需验证码。

如果你的客户端屏蔽了提示（例如在 YOLO／绕过模式下）、不支持 MCP 引导，或对话框被关闭，服务会自动在浏览器中打开一个临时本地验证表单。工具也会返回 ACCESS_INPUT_REQUIRED 和该表单的链接，因此如有需要，你可以在运行 MCP 服务的计算机上自行打开。请在浏览器表单中输入邮箱，然后打开收件箱中的登录链接。点击验证此设备，然后调用 chrome_status 继续。 本地表单会在 10 分钟后过期；再次调用工具即可获取新的表单。打开表单不会发送邮件；只有验证邮箱链接和设备授权后，访问才会开放。仅安装扩展不会激活访问权限。 4. 如果 Chrome 尚未配对，请点击 Connect。 全新安装会打开扩展程序的设置页面，其中有一个 Connect 按钮（工具栏弹出窗口中也有）。点击该按钮，允许 Chrome 请求的一项 权限，即可完成配对：服务器每次启动时，都会向 Chrome 注册一个小型辅助程序，而该按钮会向它请求端口和令牌。Chrome 只允许此扩展程序与该辅助程序通信。如果服务器更改了令牌，扩展程序会自动获取新令牌。无需复制或粘贴任何内容。

5. 在 Chrome 中批准应用连接。 运行 chrome_status，然后打开扩展程序弹出窗口中的 App connections 部分。将密钥指纹与工具结果中的指纹进行比较，然后点击 Approve for 8 hours。 应用名称由应用提供；密钥用于标识此特定会话。批准后重试该工具。即使客户端隐藏了提示，问号徽标和弹出窗口也会显示待处理请求。可直接在弹出窗口或设置中批准、拒绝、撤销和恢复连接。

每个应用会话都有自己的签名密钥，该密钥仅保存在该服务器会话的内存中。 批准在此 Chrome 配置文件中有效 8 小时。重启应用的 MCP 连接会生成一个新密钥，需要重新批准。Remove access 会阻止该密钥执行后续命令；已在运行的操作可能会完成。YOLO、绕过权限模式和 --no-email-verification 都无法跳过此扩展程序检查。

6. 允许访问所需的网站。 弹出窗口会显示网站访问请求。 点击 Allow，然后在 Chrome 显示网站权限提示时接受。此操作会一次性将该网站添加到 Chrome 和服务器的允许列表中。 允许网站后，已批准的应用便可读取该网站并在其中执行操作，包括发送消息、删除信息和进行购买；具体取决于配置的工具权限。每项操作无需单独获得扩展程序批准。网站访问权限会一直保留，直到将其移除，并由已批准的应用会话共享；每个应用仍需单独获得尚未过期的连接批准。 移除网站时，也会移除其 Chrome 权限。现有服务器标志不会授予 Chrome 访问权限，升级后也可能需要重新批准网站。

需要时，Cookie 和下载会在 Extra permissions 下分别请求权限。这些权限默认关闭，其对应按钮也可用于移除权限。下载内容时不会使用浏览器 Cookie，会拒绝重定向，且文件大小限制为 50 MiB。需要使用已登录浏览器会话或会重定向的链接可能无法使用。代理 身份验证和 IP 查询会在设置中请求权限。Chrome 不支持将 debugger 或 proxy 设为可选权限；这两项仍为必需权限，而且执行 debugger 命令前仍会检查网站权限。

使用客户端批准功能前，请更新扩展程序和服务器。旧版扩展程序无法强制执行此功能，而更新后的服务器在扩展程序更新前会拒绝浏览器命令。请参阅客户端批准详情。

**徽章位置：**徽章显示在 Chrome 工具栏中的扩展程序图标上，而不是 chrome://extensions 页面上。Chrome 会将新扩展程序隐藏在地址栏右侧的拼图按钮后面，因此请点击该按钮，找到 MCP Browser Extension，然后点击旁边的图钉一次；之后图标就会固定在工具栏中。将鼠标悬停在图标上可查看文字状态。

手动备用方案（使用 --no-native-host 关闭辅助程序，或 Connect 报告问题时）：运行 npx -y mcp-browser-extension@latest --print-pairing，打开扩展程序的 Settings，然后粘贴 ~/.mcp-browser-extension/handshake.json 中的 port 和 token。

重启 Chrome 后扩展程序消失

运行只读诊断，查看实际安装类型、缺失文件、Chrome 停用原因以及任何冲突的扩展程序注册信息：

npx -y mcp-browser-extension@latest extension doctor

旧的未打包副本在更新时，如果清单中加入了 Web Store 公钥，可能会获得新的 ID。随后 Chrome 会为同一文件夹保留两个 ID，并在下次启动时跳过该文件夹。现在更新会保留现有 ID。对于已受到这一特定冲突影响的安装：

npx -y mcp-browser-extension@latest extension repair
# Review the preview, fully quit Chrome and other Chromium browsers, then:
npx -y mcp-browser-extension@latest extension repair --apply

修复程序会将原始偏好设置备份到 ~/.mcp-browser-extension/extension-repair-backups/ 下，仅移除已确认过时的注册信息，并保留当前扩展程序及其已保存的设置。Chromium 浏览器运行时，它会拒绝写入。之后重新打开 Chrome。 自定义浏览器数据位置时，请使用 --user-data-dir <directory>；要生成诊断报告，请使用 extension doctor --json。报告包含扩展程序路径和注册状态，但不包含浏览历史记录、Cookie 或配对令牌。

如果 Web Store 安装不存在匹配的过期 ID 冲突，则不会对其进行更改。如果诊断发现文件缺失、已停用的 Store 副本或没有注册信息，则需要单独诊断；此命令不会臆测原因或重置浏览器配置文件。从未打包副本迁移到 Store 版本时，请先移除未打包副本，再从 Store 安装。

运行多个会话

每个 MCP 主机会话（每个 Claude 终端、标签页或窗口）都会启动自己的 MCP Browser Extension 服务，并同时共用你的 Chrome。最先启动的会话会占用 桥接端口并接入扩展程序，成为 hub。之后启动的每个会话都会找到一个正在运行的 MCP Browser Extension 服务所占用的端口，并以 peer 身份加入：它的工具调用会经由 hub 转发到相同的浏览器，因此每个会话都能并行工作。没有会话会断开连接。

当 hub 所属的会话结束时，其 peer 会争抢端口；其中一个会接管端口 （使用相同的令牌，因此扩展程序会在几秒内自动重新配对），其余会话则加入新的 hub。此时正在执行的调用会失败一次，返回 EXTENSION_DISCONNECTED，并会在安全可重试时自动重试。

Peer 使用 0600 握手文件中的配对令牌向本地传输进行身份验证。仅凭该令牌无法授权浏览器命令：每个会话都必须使用在 Chrome 中获准的密钥为自己的命令签名。无法共用端口的旧版服务会像之前一样被替换：系统会先验证它是否为 MCP Browser Extension 服务，再将其停止。任何未经验证的 MCP Browser Extension 服务都不会被触碰——如果端口由其他程序占用，系统会报告情况，但绝不会将其终止。

各个会话共用一个浏览器，因此也共用其标签页：如果两个会话同时操作同一个标签页，就会相互干扰。请为每个会话使用各自的标签页（tab_new），或各自的 Chrome 配置文件（见下文）。

每个会话也可以同时操作多个浏览器：在每个 Chrome 配置文件中加载扩展程序，它们都会配对到同一个服务，并分别使用自己的配置文件名称。工具会操作当前活动配置文件——在启动时使用 --profile <name>，或在运行时使用 profile_use 工具来选择。

名称会自动分配。Chrome 不会告知扩展程序它运行在哪个配置文件中，因此每次安装都会保留一个随机 ID，由服务为其命名：第一个浏览器名为 default，接下来是 profile-2、profile-3，依此类推。名称存储在 ~/.mcp-browser-extension/profiles.json 中，因此浏览器重启后仍会保留名称。 chrome_status 会列出所有已配对的浏览器（并显示其活动标签页作为提示），而 profile_rename 可为其中一个浏览器设置易记的名称（profile-2 → work）。如果想自行固定名称，可在扩展程序的 Options → Profile 中输入；该设置始终优先。

不使用 --port 时，每个服务都会绑定一个临时端口（绝不会冲突），但每次启动时端口都会变化，因此每次都需要重新配对扩展程序。若要只配对一次，请固定使用 --port 和 --persist-token。

Windows

不需要使用 WSL2——原生 Windows 即可。不过需要修改一项配置： 在 Windows 上，npx 是 npx.cmd，属于批处理脚本，而 MCP 宿主启动服务时 不会通过 shell 启动，因此无法执行 .cmd。所以 "command": "npx" 无法 启动。请用 cmd /c 包装：

{
  "mcpServers": {
    "mcp-browser-extension": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "mcp-browser-extension@latest",
               "--allow-domain", "example.com", "--enable-mutations",
               "--persist-token"]
    }
  }
}

也可以通过 Claude Code 执行：claude mcp add mcp-browser-extension -- cmd /c npx -y mcp-browser-extension@latest --allow-domain example.com

正常使用时，请按照上文所述从 Chrome 网上应用店安装扩展，然后点击 Connect。Windows 常规设置中不要使用 Load unpacked。未打包的开发版与网上应用店版本具有相同的扩展 ID， 因此加载开发版可能会替换网上应用店的安装版本；之后 Chrome 可能会停用非网上应用店版本。如果你正在开发 mcp-browser-extension，请在单独的 Chrome 配置文件中加载 %USERPROFILE%\mcp-browser-extension。

这些工具涵盖标签页、导航、交互（click/type/press/hover/ scroll/select_option）、读取（get_text/get_html/screenshot/eval/wait_for）、 无障碍 snapshot（包含可交互元素及稳定的 ref，供模型定位，而不必猜测 CSS 选择器）、会话访问（get_cookies/storage）、 辅助工具（extract_links/read_as_markdown/fill_form/download_file/upload_file）、 以及 chrome_status。upload_file 无需通过操作系统对话框，即可在文件 <input> 中设置本地文件（需要 --enable-uploads）。

click/type 支持设置 trusted: true，以使用真实的操作系统级输入（适用于 React/Vue 受控输入）；交互会自动等待目标出现。

随处使用 — --tunnel

通过 claude.ai、Claude 移动应用、ChatGPT、另一台机器上的 Claude Code，或运行在服务上的 Agent， 驱动你电脑上的 Chrome。

brew install cloudflared            # once (Windows: winget install --id Cloudflare.cloudflared)
npx -y mcp-browser-extension@latest --tunnel --allow-domain example.com --enable-mutations

它会打印一个连接器 URL，例如 https://<random>.trycloudflare.com/mcp/<key>：

• claude.ai / Claude 移动应用： Settings > Connectors > Add custom connector，粘贴 URL。
• ChatGPT（网页）： Plugins > Add > Add custom MCP server。选择 Server URL， 粘贴完整的连接器 URL（包括 /mcp/<key>），然后选择 No authentication。创建并安装个人插件，然后在新聊天中使用 @ 选择该插件。保持隧道运行。
• 在其他位置运行的 Claude Code / Agent： 使用 <url>/mcp，并设置 Authorization: Bearer <key>； 同时也会打印准确的 claude mcp add 命令。

密钥（32 个随机字节，保存在 ~/.mcp-browser-extension/remote-key）会保护每个 请求；密钥错误或缺失时会直接返回 404。任何持有该 URL 的人都能在允许的网站范围内操控 你的浏览器，因此请妥善保管 URL，并严格限制允许列表。--rotate-remote-key 会切断所有客户端连接。快速隧道 URL 每次启动都会变化；单独使用 --http 时，服务会监听 127.0.0.1:38018（--http-port），供你 自行搭建隧道（ngrok、Tailscale Funnel、反向代理）。服务会一直运行，直到按下 Ctrl-C。

每个 Chrome 配置文件单独设置代理 — proxy_status

Chrome 会将代理应用于整个配置文件，而不是单个标签页，因此请为每个 IP 使用一个 Chrome 配置文件： 在该配置文件的扩展程序 Settings 页面中设置代理，并在那里为配置文件命名，然后使用 profile_use 切换。代理失效时， 网页会加载失败，而不会回退到你的真实 IP。proxy_status 会报告出口 IP 和国家/地区；Agent 无法更改代理或读取其密码。

同时操作多个标签页 — batch

batch 可在 一个 请求中运行多个工具调用——parallel（默认）或 serial（可选 stopOnError）。每个子操作都经过与直接调用相同的策略门控、速率限制和错误处理（不会绕过，也不能嵌套）。可用它将任务分发到多个标签页：

// open three product pages (background, so they don't fight for focus)…
{ "name": "batch", "arguments": { "ops": [
  { "tool": "tab_new", "args": { "url": "https://a.example/p" } },
  { "tool": "tab_new", "args": { "url": "https://b.example/p" } },
  { "tool": "tab_new", "args": { "url": "https://c.example/p" } }
]}}

// …then read them all at once (wall-clock ≈ the slowest one, not the sum)
{ "name": "batch", "arguments": { "ops": [
  { "tool": "get_text", "args": { "tabId": "<a tabId>" } },
  { "tool": "get_text", "args": { "tabId": "<b tabId>" } },
  { "tool": "get_text", "args": { "tabId": "<c tabId>" } }
]}}

在 parallel 模式下，针对标签页的操作必须传入明确的 tabId——并发时使用默认的活动标签页不安全，因此系统会拒绝请求，而不是悄悄将其路由到错误的标签页。（tab_new、tabs_list、chrome_status 除外。）

Agent 在自己的标签页中工作，而不是你的标签页。 tab_new 会在后台打开标签页，该标签页随后成为 Agent 的标签页：未指定 tabId 的调用会发送到该标签页。如果 Agent 还没有自己的标签页，未指定标签页的 navigate 会新开一个，而不是替换你的页面；tab_new 只会复用自己打开的空白标签页，不会复用你的“新标签页”。在 Agent 打开任何内容之前，读取操作会查看你的活动标签页，因此“总结此页面”仍然有效；要操作你的页面，Agent 会传入从 tabs_list 获取的 tabId。传入 active: true 可将标签页置于前台。

访问 iframe 和 shadow root

选择器“应该”能匹配元素却没有匹配到，几乎总是因为元素位于选择器无法访问的地方：<iframe> 内部（结账组件、OAuth 同意屏幕、嵌入式编辑器），或 Web 组件的 shadow root 内部。

shadow root 会自动处理——现在，每个选择器和每个 ref 都会通过开放的 shadow root 解析，因此 snapshot 显示的任何内容都可以点击。（以前它会显示无法点击的元素：快照会遍历 shadow root，但操作不会。）

Frame 需显式启用，因为是否访问 frame 应由你决定：

frames_list {}                                  // what frames exist, and their URLs
click { "selector": "#pay", "allFrames": true } // find it in whichever frame has it
get_text { "frameId": 7 }                       // pin one frame

每个 frame 在执行任何操作前，都会根据其自身的 URL 进行授权，因此，允许列表中的页面嵌入第三方 iframe，不会成为读取第三方内容的途径。来源不在允许列表中的 frame 会被跳过。

查看页面出错的原因 — console_logs、network_log、dialogs

读取 DOM 可以告诉你页面出错后的样子，却无法说明原因。启用 --enable-observers 后，页面内钩子会记录控制台输出、未捕获的错误和 fetch/XMLHttpRequest 流量，并拦截原生对话框：

console_logs { "level": "exception" }    // the uncaught error behind a broken page
network_log  { "failedOnly": true }      // the 500 behind the blank screen
dialogs      { "policy": "accept" }      // answer confirm() with true from here on

它默认关闭，而且这是有意为之：该钩子会在真实浏览器中每个允许列表页面上修改 console、fetch、XMLHttpRequest 和对话框函数。启用后，它只会在允许列表中的域名上、于 document_start 时注册（因此可以捕获加载时发生的故障），并且记录的内容在工具调用读取之前不会离开页面——读取时也会经过与其他页面读取相同的门控。

拦截对话框不只是观察，也是在修复问题：alert/confirm/beforeunload 会阻塞渲染进程，因此以前，打开对话框的点击会让每个注入脚本一直挂起，直到命令超时并报告 TIMEOUT，却没有任何线索。启用观察器后，对话框会得到响应（默认执行 dismiss：confirm → false，prompt → null），并被记录。

network_log 能看到什么： 页面代码发出的请求——fetch 和 XMLHttpRequest，包括方法、URL、状态和耗时——以及你要求记录时的 Resource Timing 条目（脚本、图像、样式）。不包括文档请求、重定向或标头。这是为了不让调试器会话持续占用你的浏览器而付出的代价。

仅查看变更内容 — snapshot { diff: true }

快照是工具功能中成本最高的读取操作，而最常使用它的循环（snapshot → click → snapshot）每次都会重新发送几乎完全相同的页面内容。改为请求差异：

snapshot { "diff": true }                       // added / removed / changed only
click { "selector": "#save", "snapshotAfter": true }   // what the click changed

节点通过角色和可访问名称在快照之间匹配，而不是通过 ref——每次快照都会按文档顺序重新编号 ref，因此若按它们进行差异比较，上方一旦出现任何内容，一个未发生变化的按钮就会被报告为先删除再添加。

记住页面并在之后捕捉变化 — page_watch

保存一个命名的无障碍检查点，然后在之后的会话中将当前页面与之进行比较。检查点保存在当前 Chrome 配置文件下，因此工作和个人浏览器身份彼此分开：

page_watch { "action": "create", "name": "Vendor pricing" }
page_watch { "action": "compare", "watchId": "watch_…" }
page_watch { "action": "list" }
page_watch { "action": "delete", "watchId": "watch_…" }

结果会显示新增、移除和更改的控件。它会存储无障碍标签和控件状态，剥除 URL 查询字符串，应用已配置的脱敏规则，并且绝不会保存实时表单值。创建或比较检查点仍要求页面所属域名已获准访问。

按角色和名称定位

操作接受定位器，而非 CSS 选择器，因此你无需先获取快照来查找 ref：

click { "role": "button", "name": "Sign in" }
type  { "role": "textbox", "name": "Email", "text": "[email protected]" }

解析在服务端进行，且不会猜测：如果定位器有歧义，操作会失败并列出候选项，而不会直接作用于第一个候选项（传入 nth 即可选择）。

会话过期了吗？— auth_check 和 failOnAuthWall

复用已登录的 Chrome 可以省去登录步骤，但会话 Cookie 仍可能在运行过程中失效。如果没有明确的信号，下一步操作会以 SELECTOR_NOT_FOUND 或 TIMEOUT 失败，而评估运行的测试框架会将其判为 Agent 失败，实际上它只是身份验证失败。现在，每个 snapshot 都会在页面看起来像登录墙时附带 authWall 判定，并且提供了专用的探测工具：

auth_check {}                                   // { authRequired, confidence, signals }
auth_check { "failOnAuthWall": true }           // [AUTH_REQUIRED] error instead
navigate  { "url": "https://app.example.com/dashboard", "failOnAuthWall": true }
snapshot  { "failOnAuthWall": true }

对于测试框架，只需设置一次，无需每次调用都设置：

npx -y mcp-browser-extension@latest --allow-domain app.example.com --enable-mutations --fail-on-auth-wall

启用此标志后，每个可能改变标签页内容的步骤（navigate、click、type、select_option、press、fill_form、back、forward、reload）都会检查其到达的页面；如果该页面是登录墙，则会以 [AUTH_REQUIRED] 失败。如果 wait_for 在此类页面上超时，也会报告 [AUTH_REQUIRED]，而非 [TIMEOUT]。每个受保护的步骤都会额外花费一次快照往返；关闭此标志则不会产生额外开销。测试框架遇到 [AUTH_REQUIRED] 时，会暂停并让人工在同一个 Chrome 中重新登录，然后重试该步骤。MCP Browser Extension 不会自行重新进行身份验证：它按设计不持有任何凭据。

检测只读取快照中已有的信息：URL（登录路由、身份提供方主机，例如 accounts.google.com、login.microsoftonline.com、Okta、Auth0）、标题、密码字段和登录控件。high 置信度需要两个独立线索（例如，密码字段和登录按钮）；单独的密码字段或简单的 /auth/... URL 属于 medium。普通页面上的“登录”链接永远不会被计入。failOnAuthWall 仅在置信度为 high 时触发，因此测试框架可以将 [AUTH_REQUIRED] 与其他所有失败分别归类，而包含“当前密码”字段的设置页面则会正常继续。

打印 — print_pdf

print_pdf { "landscape": true }

它通过 Chrome 自带的打印流程进行渲染，并将文件保存到任务的 results/ 目录，返回路径和大小。PDF 文件本身不会被返回——PDF 有数 MB，而模型无法读取 base64 内容。

每轮降低开销 — --tools

每个已连接的 MCP 服务都会在你向它提出任何请求前占用上下文：宿主每一轮都会向模型发送完整的工具目录。MCP Browser Extension 的 43 个工具包含 28 KB 的 JSON Schema，每轮约占 7.1k 个 token。

大多数运行只需要其中少数几个。--tools 只会公布指定工具：

npx -y mcp-browser-extension@latest \
  --allow-domain app.example.com --enable-mutations \
  --tools tabs_list,tab_new,navigate,snapshot,click,type,get_text

这样工具列表只有 6.0 KB，约 1.5k 个 token——比完整目录减少 78%；适用于本来就不需要打印 PDF 或上传文件的运行。

• 以逗号分隔，并可重复使用：--tools navigate,get_text --tools click。
• 未包含的工具会从 tools/list 中隐藏，调用时也会被拒绝——batch 操作如果指定了此类工具，会像指定未知工具一样失败。隐藏工具是一种真正的限制，而非显示筛选。不过，这不能替代策略门控：没有 --unsafe-enable-eval，--tools eval 仍不会执行任何操作。
• 未知名称会在启动时导致失败并打印工具目录，因此拼写错误绝不会悄悄地将 click 从工具列表中移除。
• mcp-browser-extension --help 会打印完整的 43 个工具名称目录供选择。

状态

v0.5.0 — 安全的多标签页并发。 新增 batch 扇出工具，使并行标签页自动化不再发生竞态（显式 tabId 守卫；按标签页串行化 chrome.debugger 操作；无冲突的 tab_new），通过 chrome.debugger 截取屏幕截图（针对指定标签页且不会抢占焦点，还支持真正的整页和元素截图），并默认聚焦新打开的标签页。包含 111 项自动化测试，以及一项受控的有头扩展冒烟测试。

v0.2.0 — 六个构建阶段全部完成且通过。端到端流程已可运行： npx mcp-browser-extension ⇄ 桥接 ⇄ 扩展 ⇄ 你实际使用的 Chrome，并带有 Playwright CDP 回退方案。v0.2 新增无障碍 snapshot 和元素引用、自动等待、Cookie／存储／select_option、可信输入（chrome.debugger）、工具栏状态徽章，以及稳定的配对令牌（--persist-token）。

• 阶段 0 — 契约与骨架： shared/protocol.ts（通信契约）， src/executor/types.ts（Executor 接口），src/security/policy.ts （默认拒绝策略 + 能力门控），src/config.ts（CLI／环境变量／策略 解析），构建与测试框架。
• 阶段 1 — MCP 服务 + StubExecutor： mcp/server.ts（标准输出干净的 stdio），mcp/tools.ts（28 项工具目录 + 永不抛出错误的分发 + 偏差检查），验证器／封装对象／辅助函数，ExecutorManager + StubExecutor，cli.ts。现在即可将 MCP 主机指向 node dist/src/cli.js。
• 阶段 2 — WebSocket 桥接 + 身份验证： bridge/server.ts（回环 WS、 hello 令牌门控、welcome／unauthorized、连接置换），bridge/auth.ts （每次启动生成 256 位令牌、原子式 0600 握手、SHA-256 timingSafeEqual）， bridge/connection.ts（ID 关联、按方法区分超时、背压、关闭时拒绝所有请求、 心跳）。
• 阶段 3 — ExtensionExecutor + CdpExecutor + 选择： executor/extension-executor.ts（通过桥接实现 Executor）， executor/cdp-executor.ts（Playwright 连接／启动 + 锁恢复 + 标签页解析），executor/select.ts（扩展 ping 有响应时使用扩展，否则 使用 CDP）。CLI 现在会启动桥接、写入 0600 握手信息，并提供真实后端。新增 playwright。
• 阶段 4 — MV3 扩展： extension/ — manifest.json、 sw/ws-client.ts（拨号 + hello／welcome + pong）、sw/executor.ts （chrome.scripting／chrome.tabs 命令实现）、sw/router.ts（永不抛出错误 + 偏差检查）、sw/background.ts（顶层监听器 + 25 秒保活／重新连接）， 选项页面（手动配对），esbuild 构建 → extension-dist/。已通过实时 --load-extension 冒烟测试验证（配对 → 导航 → get_text）。新增 esbuild + @types/chrome。
• 阶段 5 — 辅助工具、下载、HITL： 强化 download_file （shared/download.ts — 路径遍历／危险扩展名净化 + 大小上限， 接入两个后端）、增强版 read_as_markdown，以及人在回路中的 测试框架（hitl/ — npm run test:hitl [-- --include-mutating]）， 使用纯函数和经过单元测试的门控。包含 50 项自动化测试。
• 阶段 6 — 打包与文档： files 白名单（仅打包 dist/src、 dist/shared、extension-dist、LICENSE、蓝图，不包含源代码／测试）， prepack 构建、bin、快速入门 + .mcp.json 片段。已通过 tarball 安装 冒烟测试验证（npm pack → 安装 → MCP tools/list）。

安全态势（默认）

默认拒绝的安全模式。 未配置策略时：允许列表为空，禁用 eval、下载和修改类工具。需明确选择启用：

mcp-browser-extension --allow-domain example.com --enable-mutations
mcp-browser-extension --policy ./policy.json          # see policy.example.json
mcp-browser-extension --enable-observers              # console/network/dialog capture (patches page globals)
mcp-browser-extension --redact                        # scrub secret-shaped strings out of page reads

无需重启即可允许网站。 如果因网站不在允许列表中而拒绝调用，扩展程序的工具栏图标会显示 ?。点击图标：弹出窗口会列出被拦截的网站，并显示一个 Allow 按钮；还会显示你当前所在的网站是否已获允许（并提供单独的 Allow 按钮），以及已允许的网站列表。选项页面（弹出窗口中的 Settings）也有一个输入框，可用于允许其他网站。允许某个网站后，所有共用此 Chrome 的会话会立即生效；该设置会保存到 ~/.mcp-browser-extension/allowed-sites.json，因此重启后仍然有效。可在此处移除通过该方式允许的网站；通过 --allow-domain 允许的网站会一直保留，直到更改标志。全匹配模式不会授予访问权限。启动前，请从旧配置中移除已弃用的 --unsafe-all-domains 选项。Agent 无法自行批准网站：MCP Browser Extension 从不读取或驱动扩展程序自身的页面。使用 --no-site-grants 运行，可确保允许列表严格遵循标志指定的内容。

返回的内容同样受到限制。 允许列表决定哪些页面可以读取，但不限制页面上的内容。已登录的页面经常会将会话令牌渲染到脚本标签中，或将 API 密钥显示在设置页面上。

• 默认隐藏 Cookie 值。 get_cookies 会返回每个 Cookie 的名称、域名、路径和标志，并将值替换为 [hidden]。会话 Cookie 无需密码即可授予账户访问权限。 如果任务确实需要 Cookie 值，请传入 --enable-cookie-values。
• 始终屏蔽密码字段的值——在 get_html 中会屏蔽；在 snapshot 中字段仍会显示（因此你可以在其中输入），但会标记为 secret: true 且不含值。没有标志，也无需选择启用：没人想要那些字符。
• --redact 还会从 get_text、get_html、read_as_markdown 和 eval 的结果中清除类似机密的字符串——JWT、AWS/GitHub/Slack/Google 密钥、Bearer 标头、私钥块。此功能需要主动启用，因为某个模式迟早会匹配到你实际需要的内容。--redact-pattern <regex> 可添加自定义模式（并隐含启用 --redact）；如果模式无效，启动时会报错，而不会悄悄导致匹配失效。
• 截断输出之前会先执行脱敏，因此，截断读取不会泄露完整读取本应隐藏的内容。

每次调用都会记录到任务的 history.jsonl 中，包括访问的 URL、策略判定结果（allowed/denied）、耗时、返回的字节数以及清除的机密数量。这样，事后也能回答“Agent 在我的浏览器中做了什么”。

每次启动时生成的 256 位令牌存储在 ~/.mcp-browser-extension/handshake.json 中（模式为 0600），它是唯一的信任边界；令牌绝不会写入 stdout/stderr。在 POSIX 系统上，每次写入后都会重新验证权限；如果文件最终允许组用户或其他用户访问，服务会默认拒绝运行。Windows 没有这类权限位——在那里，chmod 只会切换只读属性——因此会跳过检查，令牌的机密性依赖于 %USERPROFILE%\.mcp-browser-extension 的每用户 ACL。

更新

无需进行任何操作即可保持最新。上文的安装片段使用 @latest；此外，已安装的副本（通过 npx 或全局安装）启动时会检查 npm：如果发布了更新版本，就会使用相同参数启动该版本，以替换当前版本。因此，几个月前编写的 MCP 配置仍会运行最新版本。离线时，检查会在 1.5 s 后放弃；从 git 检出目录运行的副本不会自行更新。新服务还会刷新 ~/mcp-browser-extension 中解压的扩展程序，并让其自行重新加载；Chrome Web Store 版本则照常通过 Chrome 更新。使用 --no-auto-update 或 MCP_BROWSER_EXTENSION_AUTO_UPDATE=0 可关闭此功能。

遥测

MCP Browser Extension 服务（而非扩展程序）会向 PostHog 发送匿名使用统计信息，以便项目了解有多少安装处于活跃状态、正在使用哪些版本和平台，以及哪些工具最常出错。它首次运行时会显示一条通知。

发送的内容：随机安装 ID（保存在 ~/.mcp-browser-extension/telemetry.json 中）、服务版本、操作系统、CPU 架构和 Node 主版本、当前会话是独占桥接端口还是与其他会话共享、有多少浏览器已配对、已配对扩展程序的版本及其是商店版本还是未打包副本，以及每个工具的调用和错误计数及错误代码。首次批次会在首次工具调用一分钟后发送，之后每 10 分钟发送一次。对于 PostHog 的 MCP Analytics 视图，每次工具调用也会作为一个 $mcp_tool_call 事件发送，仅包含工具名称及其分组（读取、导航……）、调用时长、是否失败及错误代码、MCP 客户端的名称和版本（例如 claude-code）、MCP 协议修订版本、客户端在其请求元数据中提供的 AI 模型（Codex 会提供），以及一个在闲置 30 分钟后更换的随机会话 ID。客户端连接时，会记录一个事件，包含该握手信息和所提供工具的名称。不会发送 Agent 发送或读取的任何内容：没有参数、结果、错误消息或意图。每 15 秒批量发送一次。启动一分钟后会发送一个 pair_check 事件，说明是否有浏览器完成配对；如果没有，则记录适用的几种固定原因之一（no_extension、token_mismatch、version_mismatch、profile_mismatch），以便在问题发生处解决设置问题。

绝不会发送的内容：URL、域名、工具参数、页面内容、屏幕截图、Cookie、配置文件名称、令牌、文件路径或你输入的任何内容。事件不包含个人信息，并且已禁用 GeoIP 查询。

浏览器扩展程序不会发送任何内容——它只会与 127.0.0.1 通信。

可通过以下任一方式关闭：

MCP_BROWSER_EXTENSION_TELEMETRY=0     # or false / off
DO_NOT_TRACK=1
--no-telemetry             # server flag

了解更多

完整文档、各 MCP 客户端的设置指南和安全模型均可在网站上查阅：MCP Browser Extension 文档。

• 什么是 MCP 浏览器扩展程序，什么时候需要使用它
• 在已登录的 Chrome 中使用 Claude
• 为 Claude Code 提供浏览器访问权限
• 通过 MCP 为 Cursor 提供真实浏览器
• 让 VS Code Copilot 使用你的真实 Chrome
• 使用 AI Agent 端到端测试登录流程
• 通过浏览器 MCP 隧道检查发布页面
• Chrome DevTools MCP 与 Playwright MCP 及 MCP 扩展程序对比
• 2026 年最佳浏览器 MCP 服务
• 与其他浏览器 MCP 服务的对比

开发

npm install
npm run typecheck       # server/test sources
npm run typecheck:ext   # extension sources (@types/chrome)
npm run build:ext       # bundle the extension → extension-dist/
npm test                # builds, then runs node --test on dist/test
RUN_EXT_SMOKE=1 node --test dist/test/extension-smoke.test.js   # live, headed

扩展

已在 Chrome 网上应用店发布，名称为 MCP 浏览器扩展。 只有在 extension/ 发生更改时，扩展版本才会更新，因此所列构建版本可能比 npm 包落后一版；两者会在连接时协商功能，因此较旧的扩展只会缺少功能，不会导致故障。

正常使用时，请从上方的 Chrome 网上应用店安装。以下内容仅适用于本地开发；请勿在与网上应用店扩展相同的 Chrome 配置文件中加载此未打包副本。在 Windows 上，Chrome 可能会停用非网上应用店版本。

extension/ 会通过 esbuild 构建到 extension-dist/，然后在 chrome://extensions 中选择 加载已解压的扩展程序 → 选择 ~/mcp-browser-extension 加载；这是服务在每次启动时从 extension-dist/ 刷新的镜像（也可以直接加载 extension-dist/）。扩展会从服务写入该文件夹的 pairing.json 中读取配对信息；只有在备用情况下，才需要在 选项 页面粘贴 ~/.mcp-browser-extension/handshake.json 中的 port 和 token（运行 npx -y mcp-browser-extension@latest --print-pairing 即可获取路径）。

读取和交互使用 chrome.scripting/chrome.tabs —— 不会显示“正在调试”横幅，支持符合 CSP 的读取（隔离世界），可在 Playwright 下测试。 仅在必要且值得使用时才会使用 chrome.debugger：用于 trusted: true 输入（在 React/Vue 输入框中触发真实的操作系统级事件）和 screenshot（截取指定标签页，无需激活该标签页——可在并行 batch 中安全使用，并支持真正的整页和元素截图）。这些操作在调试器连接期间会显示调试横幅；最后一次操作结束后，会话会保留 1.5 秒，因此一连串操作只需连接一次。截图默认采用 JPEG 格式（质量 70），尺寸为 CSS 像素；传入 format: "png"、quality 或 scale 可更改设置。