Browser Mcp

Agent360 的 Browser MCP

会停下来询问你的浏览器工具。 2FA 验证码、CAPTCHA，或只有你才能做出的选择：它会在你自己的屏幕上询问，然后继续使用同一个已登录的 Chrome。

它操控的是你已经登录的 Chrome：没有可能失败的登录步骤，无需配置 API 密钥，也不会使用对你所有账号都陌生的新配置文件。最多可同时运行 20 个 Agent，每个 Agent 都在自己独立的彩色标签组中。40 个工具，采用 MIT 许可证，可在你的机器上运行。

→ 它能和不能突破的限制 - 每项限制都标记为 已实测、出于设计、尚未实现 或 不会实现。包括我们尚未解决的限制。

▶ 观看 15 秒短片 →

Browser MCP 让 Claude Code（以及运行本地服务的 MCP 客户端，例如 Cursor 和 VS Code Agent 模式）能够控制你实际使用的 Chrome：你的 Cookie、会话和 2FA。因此，在 CAPTCHA、2FA 和反机器人网站上，即使 Playwright 和 Puppeteer 会被拦截，它也能正常工作——因为浏览网页的是你。

杀手级功能：遇到登录拦截时，它会打开你的 Gmail，读取验证码，然后继续登录。无需配置电子邮件 API。操作没有 API 的平台、端到端测试你自己的 Web 应用，或以真人速度处理仪表盘、LinkedIn 和 Reddit——敏感步骤由你批准。

40 个工具。可自动点击 reCAPTCHA v2 复选框，其余情况则由真人接手。多会话彩色标签组。MIT 许可证，免费，并在你的机器上运行——无需账号，不收集遥测数据，也不会向我们发送任何内容。

整个流程，四个步骤

不想手动操作？ 把下面这段话发给你的 AI 助手——Claude Code、Cursor、Codex、VS Code、Windsurf 或 Cline——它就会自行完成设置：

帮我设置 Browser MCP。阅读 https://browsermcp.dev/llms-install.md，并按照说明为你正在运行的 AI 客户端进行设置。只有一步需要我来完成：告诉我是哪一步，然后等我操作。等我确认后，调用 browser_list_tabs，证明两部分都已连通。

如果你无法打开 URL：npx @agent360/browser-mcp install

它会读取与下面四个步骤相同的指南。无论如何，有一步需要你来完成：Chrome 不允许扩展自行安装，因此你需要手动加载一次。

1 - 安装 Chrome 扩展。 在 Chrome 网上应用店中点击一次即可；Chrome 会为其自动更新。无法使用应用店？请参阅下方的未打包安装方法。

2 - 添加 MCP 服务。 在终端中粘贴以下命令。此步骤为必需——扩展本身不会执行任何操作：

claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest

3 - 重启 Claude Code。 这样才能启动服务。在第 4 步之前，扩展不会显示徽标——只有在你的 Agent 首次实际使用浏览器时，服务才会占用一个端口。届时会出现绿色徽标，并显示已连接的 Agent 数量；在此之前图标上没有任何标记是正常的。（图标本身不会改变颜色——变绿的是徽标。）

4 - 说出这句话，检查是否生效。 将下面这句话粘贴给 Claude Code：

打开 example.com 并截取屏幕截图。

你会收到一张图片，而不是 “我无法访问浏览器”。就这么简单——你已经可以开始使用了。 → 还可以说什么

使用 Cursor、VS Code、Codex 或 Windsurf？使用同一个服务，但需采用对应客户端自己的配置——顶部的提示词会处理好，或者参阅 browsermcp.dev/docs。以下是完整的详细说明。

详细说明——逐步安装

Browser MCP 由两部分组成，缺一不可：一个Chrome 扩展（用于控制浏览器）和一个本地 MCP 服务（你的 Agent 实际与之通信的对象）。只安装扩展——例如直接从 Chrome 网上应用店安装——会让它一直停留在 “未连接” 状态，因为没有可连接的服务。Chrome 无法安装服务，npm 也无法安装扩展。因此需要执行两个步骤。

步骤 1：向 Claude Code 注册 MCP 服务

claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest

这是 Claude Code 自带的 MCP 命令，因此配置项会写入 Claude Code 实际读取的配置文件。--scope user 会让它在每个项目中都可用。

想要将扩展文件保存到磁盘，以便在步骤 2 中进行未打包安装？还要运行：

npx @agent360/browser-mcp install

它会将扩展复制到 ~/.browser-mcp/extension/，并在终端中打印该路径——请复制它。（如果检测到 Claude Code、Codex、VS Code 和 Cursor，它还会为它们注册服务。）

步骤 2：在 Chrome 中加载扩展

Chrome 不允许扩展从 npm 自行安装——你需要手动加载一次。之后要更新时，重新运行安装命令并重新加载扩展即可（请参阅保持更新）。如果你希望扩展自动更新，也可以通过 Chrome 网上应用店安装。

1. 打开 Chrome，并在地址栏中输入 chrome://extensions
2. 开启“开发者模式”（右上角）
3. 点击“加载已解压的扩展程序”（左上角，“打包扩展程序”旁边）
4. 导航到 ~/.browser-mcp/extension/，然后点击“选择”
   • 在 Mac 上：在文件选择器中按 Cmd+Shift+G，粘贴 ~/.browser-mcp/extension/，然后按 Enter
   • 在 Windows 上：在地址栏中粘贴 %USERPROFILE%\.browser-mcp\extension\（尚未在 Windows 上验证：我们的自动化测试在该系统上无法通过）
   • 在 Linux 上：在路径栏中输入 ~/.browser-mcp/extension/
5. 重启 Claude Code，让它加载新的 MCP 服务

就是这样。Browser MCP 图标会显示在工具栏中，Claude Code 现在可以使用 40 个浏览器工具。

替代方案：手动下载 zip（无需 npm）

如果你不想使用 npm，可以直接下载扩展：

1. 从最新的 GitHub 版本发布页下载扩展 zip（agent360-browser-mcp-<version>.zip）
2. 解压文件（任意位置，例如 ~/Downloads/browser-mcp-extension/）
3. 按照上方的第 2 步操作，但选择解压后的文件夹，而不是 ~/.browser-mcp/extension/
4. 注册服务端——运行 claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest，或手动将以下内容添加到 ~/.claude.json：

   {
     "mcpServers": {
       "browser-mcp": {
         "command": "npx",
         "args": ["@agent360/browser-mcp@latest"]
       }
     }
   }
   

Chrome 网上应用店（无需开发者模式，扩展自动更新）

此方式仅替代第 2 步——你仍需完成第 1 步。

1. 从 Chrome 网上应用店安装扩展 →——无需切换开发者模式，Chrome 会为你自动更新扩展。
2. 注册 MCP 服务：

   claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest
   

   （对于 Cursor / VS Code / Codex，请使用该客户端自己的 MCP 配置——参见 browsermcp.dev/docs。）
3. 重启 Claude Code。

跳过第 2 步，扩展图标就会永远显示 “未连接”——这说明缺少 MCP 服务，而不是扩展损坏。

已经就绪。接下来呢？

除非你提出请求，否则什么都不会发生。开始使用新工具最难的地方，就是知道该如何提问。将以下任意一句发给你的 Agent（将 example.com 替换为你自己的网站）：

可以这样说	这能说明什么
“打开 example.com 并截图。”	从这里开始。 如果返回的是图片，而不是 “我无法访问浏览器”，就说明两部分已成功连接。这就是完整的安装测试。
“打开 Gmail，告诉我最近 3 封邮件是谁发的。”	这最能体现区别——因为它使用的是你的浏览器，而且你已经登录。全新的无头浏览器在这里会遇到登录页面。
“打开我的分析仪表板，提取本月数据，并整理成表格。”	使用你已在当前 Chrome 中登录的仪表板。无需 API 密钥，无需导出，也无需先构建集成。
“在 example.com/signup 填写注册表单，使用我的信息。涉及敏感内容时，先停下来询问我。”	你始终可以参与其中——对于密码、付款信息或任何不应由它单独决定的事项，Agent 可以暂停并询问你。
“帮我登录 app.example.com。如果它通过邮件发送验证码，就打开 Gmail，读取验证码并继续。”	无需设置邮件 API 的操作方式：它会打开你的 Gmail，读取一次性验证码并完成登录。
“像真正的用户一样走完我应用的注册流程，告诉我哪里会出错。”	在用户实际使用的同一个浏览器中，对你自己的产品进行端到端 QA。

基本思路是：在你已经登录的网站上，完成许多你自己也会操作的浏览器任务。 在没有 API 的场景下，它最能发挥作用——例如内部仪表板、管理面板、门户网站和 LinkedIn。做出了不错的东西？将它添加到案例库。

为什么选择它，而不是 Playwright MCP / BrowserMCP？

	Browser MCP	Playwright MCP	BrowserMCP.io
浏览器	通过扩展使用你的真实 Chrome	默认使用持久配置文件，或通过其扩展使用你的 Chrome	你的真实 Chrome
维护情况	积极维护——最新版本为 v1.30.3（2026-10-15）	积极维护（Microsoft）	上次提交于 2025 年 4 月
登录状态/ Cookie	你现有的会话	持久配置文件会在不同运行之间保留登录状态	已通过身份验证
多个 Agent，共用一个已登录的配置文件	支持 20 个并发会话，每个会话都有独立的彩色标签组	同样支持：其扩展会为每个已连接的客户端分配独立的彩色标签组	单个会话
人工参与	browser_ask_user——用于 2FA、CAPTCHA、凭据输入	无：有 72 个已记录的工具，没有一个可以询问用户（已于 2026-09-19 检查）	无
查找 Token 的指南	内置 9 个（Stripe、HubSpot、Slack……）	无	无
绕过 CORS	通过扩展后台使用 browser_fetch	不适用	有限
网络监控	通过 CDP 使用 browser_wait_for_network	内置	无
严格执行 CSP 的网站	全程使用 Chrome Debugger API	可用	有限
自定义下拉菜单	支持 Angular Material、React Select	可用	有限
安装	claude mcp add + Chrome Web Store 中的扩展	npx @playwright/mcp	npx @browsermcp/mcp + Chrome Web Store

让其他方案都束手无策的页面

它能在无头模式失效的情况下正常工作，并不是因为它绕过了什么，而是因为根本没有什么需要绕过：这是你的 Chrome、你的会话、你的授权。剩下的难题，是那些因构建方式而与任何自动化作对的页面。

每次发布都必须通过针对真实 Chrome 的流程测试，且要经受住这些页面的考验：测试会运行全部 40 个工具，还会确认正在运行的扩展 Chrome 就是即将发布的版本，而不是另一个版本号相同的副本。实际出现的失败都如实呈现：鼠标事件不会发送到未置于前台的标签页，工具会明确说明这一点，而不是谎报成功。测试覆盖的内容：

• 严格 CSP——导航、读取、执行、等待和点击仍然都能正常工作（脚本通过 Chrome Debugger API 运行；脚本注入被阻止时，其余操作也会回退到该 API）
• 跨源 iframe——可探测并进入其中
• Shadow DOM——选择器可以穿透其中
• 受控输入框——fill 可在 React 风格的受控字段中生效
• 如实检查——click 遇到 0×0 元素时会拒绝点击，而不是点击 (0,0)；如果页面未接收事件，也会明确说明

已知限制：在未查看的标签页中操作

在未查看的标签页中，Agent 可以导航、读取内容、截图、运行脚本、点击，以及通过 CSS 选择器填写找到的字段。Chrome 不会向窗口中当前不可见的标签页传递鼠标和键盘事件，因此按键、悬停、双击、右键、坐标点击、在组合框中输入，以及通过文本找到字段后填写，都会失败并返回相应错误。Agent 随后可以调用 browser_switch_tab，将该标签页设为窗口中的活动标签页；但从 1.30.2 开始，这不会让 Chrome 显示在你面前。需要 Chrome 位于前台的输入仍可能失败，Agent 会先询问你：只有设置 bring_to_front: true，Chrome 才会移至前台。被其他窗口遮挡的窗口截图同样会返回 window-covered，而不会将 Chrome 提到前台。

这些工具会检测页面是否确实收到了事件，而不是相信 Chrome 的确认，因此后台标签页会如实报告失败，而不是悄无声息地失败。 （在 1.29.2 中引入——请参阅 CHANGELOG.md，确认你使用的版本。）

完全无需人工介入的后台输入不属于 1.30 的功能，而且我们无法解决：Chrome 不会向窗口中当前不可见的标签页传递鼠标或键盘输入（已实测）。在桌面版 Chrome 中，操作系统焦点不在窗口时，窗口的活动标签页能否接收输入尚未实测，因此工具会依据 landed 的结果作出判断。有些问题根本无法解决：CSS :hover 是由渲染器管理的状态，任何脚本都无法伪造；脚本派发的事件永远不会是 isTrusted；elementFromPoint 无法穿透跨源 iframe；而真实双击产生的文本选区属于浏览器行为，并非事件。

最后这一类问题最为重要。工具悄悄报告成功，比直接失败更糟，因为你会基于这个结果继续操作。我们仍有不足之处的地方都已记录下来：请参阅 #19。

已于 2026-09-07 更正，并于 2026-09-19 再次更正。 此表曾称 Playwright MCP 以无头模式运行，且每次都要重新登录。这是不对的。我们当时称为“唯一能持续使用”的问题——多个客户端在同一配置文件上发生冲突——也不对：该限制属于其持久化配置文件模式，而其 Chrome 扩展会明确为每个已连接的客户端分配各自的彩色标签组，这与我们在自己的表格行中描述的机制相同。我们只更正了一页，没有修正整个表述模式。真正成立的差异是需要人工参与，而这也是我们实际测量的内容：Playwright MCP README 列出了 72 个已记录的工具（于 2026-09-19 统计），其中没有任何工具能暂停操作并向用户索要验证码。

关于名称： 名称相似的 browsermcp.io（@browsermcp/mcp）是另一个互不隶属的项目，自 2025 年 4 月以来没有提交记录。这里介绍的是 Agent360 开发的 Browser MCP（@agent360/browser-mcp），目前仍在积极维护。完整对比 →

环境变量

以下 4 个变量均为可选项。正常使用时无需设置。

变量	作用
BROWSER_MCP_CHECK_NPM=1	让 browser_provide_feedback 同时将此服务与 npm 上发布的最新版本进行比较。默认关闭，因此调用速度快且可离线运行。
BROWSER_MCP_EXTENSION_ID=<32-char id>	将服务固定到某个特定的 Chrome 扩展程序。当加载了多个 Browser MCP 副本，且希望某个会话始终与其中同一个副本通信时，可使用此变量。它无法区分 Chrome 配置文件：Chrome 网上应用店中的扩展程序在每个配置文件中都有相同的 ID。BROWSER_MCP_PROFILE 可以做到这一点。
BROWSER_MCP_PROFILE=<name>	从 1.31 开始：驱动扩展弹出窗口中名称为此值（“此 Chrome 配置文件”）的 Chrome 配置文件。可使用字母、数字、点、短横线和下划线，最多 32 个字符。可与 BROWSER_MCP_EXTENSION_ID 配合使用（两者都必须匹配）。无效值不会被忽略：每次浏览器调用都会返回 profile-invalid。请参阅多个 Chrome 配置文件。
BROWSER_MCP_TOKEN	已在 1.30.1 中撤回并被忽略——服务启动时会说明这一点。配对功能在 1.30.0 中推出，但并未阻止任何人，因此团队撤回了它，而不是将其留作虚假的保护措施。此功能将以重新设计后的形式回归。

40 个工具

导航与内容

工具	说明
browser_navigate	导航到 URL（重用标签页，或设置 new_tab=true）。遇到“离开网站？”提示时，会选择“停留”并说明原因（beforeunload-blocked）；设置 leave_page=true 则会离开；已启用的 browser_handle_dialog 会代为作答，而不是执行以上任一操作
browser_get_page_content	获取页面文本或 HTML
browser_screenshot	通过 Chrome Debugger 截取屏幕截图（即使标签页未处于焦点也能使用；被遮挡的窗口会返回 window-covered）
browser_execute_script	通过 Chrome 调试器，在页面自身的上下文中运行 JavaScript（也适用于 CSP 严格的网站）
browser_extract_list	通过滚动列表容器来读取长列表或虚拟化列表中的行，直到不再出现新行；在活动标签页中使用真实滚轮事件滚动，因此依赖滚轮加载的动态信息流（Threads、X）也会加载；在隐藏页面（后台标签页）中，若列表在滚动时加载内容会提前停止，且 reached_end 为 false

交互

工具	描述
browser_click	通过 CSS 或文本选择器点击（text=Submit、button:text(Next)）；文本选择器会优先查找已打开的模态对话框；如果鼠标无法到达目标位置，则返回 covered，而不执行点击
browser_fill	填充输入字段（适用于 CSP 严格的网站）；使用文本选择器时，如果鼠标无法到达字段，则不会输入任何内容（返回 covered）
browser_press_key	键盘事件（Enter、Tab、Escape、修饰键）。使用 ctrl 或 meta 时，a、c、x、v、z、y 会分别作为 Chrome 的全选、复制、剪切、粘贴、撤销和重做命令发送
browser_scroll	滚动到元素位置或按像素滚动
browser_wait	等待元素出现
browser_hover	悬停以显示工具提示或下拉菜单；如果鼠标无法到达该位置，则返回 covered
browser_select_option	选择原生 <select> 和自定义下拉菜单（Angular Material、React Select）；如果鼠标无法到达自定义触发器或选项，则不会点击（返回 covered）
browser_set_combobox	自动补全/组合框：输入查询 → 等待筛选后的列表框 → 点击选项（支持多值标签）。当 browser_select_option 无法处理延迟渲染的选项时使用
browser_set_date	适用于日期输入框的可靠操作：尝试原生值设置 → 掩码输入 → 日历选择器导航（MUI/AntD/react-datepicker/Lexical）。当 browser_fill 无法处理日期字段时使用
browser_dismiss_overlays	通过 aria-label/文本/× 字符启发式批量关闭弹出窗口/模态框/工具提示/横幅。non_critical 模式会保留含表单数据的对话框
browser_handle_dialog	接受/关闭原生 alert/confirm/prompt/“Leave site?” 对话框：处理扩展检测到的已打开对话框，或等待下一个对话框（如果对话框在任何监听器启动前就已打开，则无法从这里处理）
browser_double_click	执行真正的双击（两组可信的按下/释放事件）；如果鼠标无法到达目标位置，则返回 covered
browser_right_click	右键点击以打开页面级上下文菜单；如果鼠标无法到达目标位置，则返回 covered
browser_click_xy	备用方案：使用可信鼠标事件点击视口中的原始坐标（CSS 像素）
browser_reattach_debugger	恢复操作：强制断开并重新连接当前标签页的 Chrome 调试器

标签页与框架

工具	描述
browser_list_tabs	仅列出会话中的标签页
browser_switch_tab	按 ID 切换标签页；除非设置 bring_to_front: true，否则 Chrome 会保持当前显示状态
browser_close_tab	关闭标签页（仅限会话拥有的标签页）
browser_get_new_tab	获取最近打开的标签页（OAuth 弹出窗口）
browser_list_frames	列出页面中的 iframe
browser_select_frame	通过 Chrome 调试器在指定 iframe 中运行 JavaScript，也支持来自其他网站的 iframe

数据与网络

工具	描述
browser_fetch	通过扩展发送 HTTPS 请求（绕过页面的 CORS 和 CSP），不使用浏览器 Cookie（不会发送或存储任何 Cookie）——在标头中传递令牌；仅对 127.0.0.1 使用普通 HTTP
browser_wait_for_network	等待特定 API 调用完成
browser_extract_token	打开已知提供商的 API 页面，并获取在该页面查找或创建令牌的说明（下文列出 9 个提供商）；此工具本身不会读取任何内容

CAPTCHA 求解

工具	描述
browser_solve_captcha	检测 CAPTCHA 并逐步处理，每次调用执行一个步骤。自动检测 reCAPTCHA v2/v3、hCaptcha、Turnstile、FunCaptcha。操作：detect、click_checkbox（尝试点击 reCAPTCHA 复选框）、click_grid（点击你选择的 reCAPTCHA 单元格；不会返回图像，因此请先截图）、ask_human（返回要通过 browser_ask_user 显示的消息）

Human-in-the-Loop

工具	描述
browser_ask_user	请你执行操作或回答问题：一个小卡片，你可以将它拖到一边，然后登录或解决 CAPTCHA；也可以是包含 2FA 代码输入框的对话框。页面可以看到你在其中输入的内容，因此这里只适合输入属于该页面的机密信息。需要页面已加载：如果当前是 Chrome 错误页面或 about:blank，它会立即失败且不显示任何内容。它会激活标签页并恢复最小化的窗口，但不会将 Chrome 置于其他应用前面。

数据

工具	描述
browser_get_cookies	获取本次会话中已打开网站的 Cookie
browser_set_cookies	为某个域设置 Cookie
browser_get_local_storage	读取页面的 localStorage
browser_set_local_storage	写入 localStorage 值
browser_console_logs	捕获页面的 console.log/warn/error 消息
browser_upload_file	通过 Chrome Debugger API 将文件上传到 <input type="file">（无需对话框）。需要为 Agent360 Browser MCP 扩展启用“允许访问文件网址”，Chrome Web Store 安装的版本默认关闭此选项；启用后，扩展也可以将任意本地文件作为页面打开，因此是否启用由你决定；否则请自行附加文件。除非 Chrome 确认文件访问已开启，否则交接过程中出现的“Not allowed”错误会报告为 file-access-off
browser_drop_file	通过拖放区域上传：如果目标是文件输入框，则使用该输入框；否则使用其中隐藏的 <input type="file">；如果两者都没有，则点击目标并拦截原生文件选择器。页面上的其他文件输入框不会收到该文件。回答会说明使用了哪个输入框；如果页面在变更处理程序检测到文件后清空了字段，则会注明 cleared_by_page。当 browser_upload_file 因区域没有可见输入框而失败时使用。需要启用同一个开关

诊断与反馈

工具	描述
browser_provide_feedback	一次调用即可进行自检并提交报告。将已连接的扩展与此服务进行比较，并检测是否同时连接了多个 Browser MCP 扩展，包括同一个扩展连接多次的情况（例如通过多个 Chrome 配置文件或浏览器连接）；设置 BROWSER_MCP_CHECK_NPM=1 后，还会将此服务与 npm 上的最新版本进行比较。这三项能解释大多数“它突然停止工作了”的情况。返回判定结果（current / outdated / conflict / disconnected / idle / unknown）、具体修复步骤，以及预先填写好的问题反馈链接，指向确实缺少的内容。每当工具阻止 Agent 执行操作时，Agent 都会自行调用此工具
browser_about	项目信息及用于提交愿望、使用场景或 Bug 的预填链接。从 1.31 版起，它还会列出与聊天连接的 Browser MCP 安装项：弹出窗口中的配置文件名称、安装 ID 和版本

多会话支持

每个 Claude Code 对话都会在一个唯一端口（9876-9895）上运行自己的 MCP 服务。Chrome 扩展会同时连接所有活动服务。

需要同时运行超过 20 个？ 这个范围是一个设置，并非硬性限制，但两端的设置必须一致。 在每个聊天的 MCP 配置中设置 BROWSER_MCP_MAX_PORT，在扩展的存储中将 bmcpPorte 设为相同范围，然后重新加载扩展：它只会在启动时读取该范围。如果只更改服务端，聊天 21 就会绑定到扩展不会检查的端口，因此该聊天中的浏览器会悄无声息地失去响应。100 个端口绰绰有余；硬上限是 200。每增加一个端口，浏览器每两秒就会多发起一次被拒绝的连接，无论你是否使用它，所以不要为了好玩而扩大范围。

Claude Session 1 ←(stdio)→ MCP :9876 ←(WS)→
Claude Session 2 ←(stdio)→ MCP :9877 ←(WS)→  Chrome Extension → Browser
Claude Session 3 ←(stdio)→ MCP :9878 ←(WS)→

• 会话隔离 - 每个会话都会获得一个带颜色标识的 Chrome 标签组
• 标签页归属 - 会话只能查看和控制自己的标签页
• 自动清理 - Claude Code 关闭对话时，进程也会退出
• 按需占用端口 - 服务会在首次调用浏览器时绑定端口，而不是在启动时绑定；最后一个标签页关闭 5 分钟后释放端口。完全不使用浏览器的聊天不会占用名额。

多个 Chrome 配置文件

Chrome 网上应用店扩展在每个 Chrome 配置文件中的 ID 都相同，因此在 1.31 之前，服务无法区分不同配置文件：如果两个配置文件都启用了扩展，命令会发往其中一个，而且目标可能变化。从 1.31 开始，每个安装实例（每个 Chrome 配置文件一个）都会报告一个安装 ID，你可以在扩展弹出窗口中的“This Chrome profile”下为其命名。在客户端的 MCP 配置中设置 BROWSER_MCP_PROFILE=<name>，该客户端便会驱动对应的配置文件。

情况	Agent 会得到什么
一个已连接的安装实例具有该名称	命令会发往该实例，且聊天从首次命令开始就会保持使用该实例
暂无实例具有该名称	调用会先等待实例连接：约 7.5 秒；如果端口在最近 10 秒内打开，则最长约 17.5 秒（聊天首次调用浏览器时，会加上下面的 2.5 秒，并将等待时间加倍），然后返回 profile-not-connected，并列出它能看到的安装实例；如果所有已连接扩展的版本都早于 1.31，则返回 profile-routing-unsupported
两个或更多实例具有该名称，或同一个实例连接了两次	立即返回 profile-ambiguous，不再继续等待。如果未设置 BROWSER_MCP_PROFILE，连接两次的实例也会被拒绝
聊天正在驱动的实例断开连接	正在执行的调用会像以前一样立即失败。下一次调用会返回 profile-disconnected；只有再下一次调用才会重新选择。如果同一实例及时恢复连接，聊天便会继续使用它
未设置 BROWSER_MCP_PROFILE	与以前一样，首次选择最新的扩展；存在多个安装实例时，下一次响应会说明选中了哪个，且聊天会继续使用该实例

聊天首次调用浏览器时，会等待端口打开约 2.5 秒后再进行选择，让每个 Chrome 配置文件都有一次扫描机会（每 2 秒扫描一次）来建立连接；否则，碰巧先连接的配置文件可能会被选中，而不会给出任何提示。在空闲机器上，余量约为半秒：如果某个配置文件的扫描晚于这个时间，例如在负载很高的机器上，它仍可能错过首次选择，之后聊天会继续使用已连接的配置文件。对于所有这些错误响应，没有任何内容发送到 Chrome（sent: false），且服务不会自行切换到其他配置文件：如果聊天的安装实例断开时某个调用仍在等待，该调用也会收到 profile-disconnected。browser_about 会列出已连接的实例。在弹出窗口中重命名不会断开任何连接或正在运行的调用；聊天已经在驱动的实例会继续由该聊天驱动。名称只是一个选择项，并非密钥：扩展的问候消息未经签名，机器上的其他程序可以冒用任何名称（见下文“安全性”）。

在另一台机器上运行 Agent

该扩展只连接到 127.0.0.1，这是有意为之——它不会连接远程 WebSocket。如果你的 MCP 网关运行在与浏览器不同的机器上，请通过 SSH 转发端口范围。

以下方案由 @bkuri 提供。他也遇到了这个问题并解决了。适用于 Linux + systemd；本机需要安装 autossh，且服务器上已配置你的公钥：

# ~/.config/systemd/user/browser-mcp-tunnel.service
[Unit]
Description=SSH tunnel for browser-mcp WebSocket (ports 9876-9895)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/bin/sh -c '/usr/bin/autossh -M 0 -N \
  -o ServerAliveInterval=30 -o ServerAliveCountMax=3 \
  -o ExitOnForwardFailure=yes -o LogLevel=ERROR \
  $(for p in $(seq 9876 9895); do printf " -L %s:127.0.0.1:%s" "$p" "$p"; done) \
  server-name'
Restart=on-failure
RestartSec=5
Environment="AUTOSSH_GATETIME=0"

[Install]
WantedBy=default.target

替换 server-name，然后运行 systemctl --user enable --now browser-mcp-tunnel.service。

最初的方案手动列出了 9876-9885 端口——当时端口范围是 10 个。现在范围是 20 个，因此上述循环会自动生成端口，而不是硬编码一个在下次范围变更时就会过时的列表。

内置的服务商集成

browser_extract_token 会打开服务商的 API 页面，并返回查找或创建凭据的说明。它本身不会读取任何内容；对于 HubSpot、Slack、Shopify 和 LinkedIn，打开的页面是前往令牌页面途中经过的设置页面或应用列表，而非令牌页面本身。其他任何服务商都会返回 Unknown provider。

服务商	令牌格式	控制面板
Stripe	sk_test_... / sk_live_...	stripe.com/apikeys
HubSpot	pat-...	app.hubspot.com
Slack	xoxb-...	api.slack.com/apps
Shopify	Admin API token	admin.shopify.com
Pipedrive	UUID	app.pipedrive.com
Calendly	JWT	calendly.com
Mailchimp	...-us1	admin.mailchimp.com
Google	OAuth Client	console.cloud.google.com
LinkedIn	Client ID/Secret	linkedin.com/developers

架构

extension/
  manifest.json       # Manifest V3
  background.js       # Service worker - Chrome API dispatcher, session tab groups
  offscreen.js        # Persistent WebSocket bridge (multi-port scanning)
  popup.html/js       # Status UI - sessions, tabs, action log

mcp-server/
  index.js            # MCP server (stdio) + WebSocket client
  tools.js            # 40 tool definitions
  bin/cli.js          # Install CLI

工作原理

1. Claude Code 启动 → 通过 stdio 启动 MCP 服务
2. 首次有工具需要使用浏览器时，MCP 服务绑定第一个可用端口（9876-9895）
3. 扩展的 offscreen 文档每 2 秒扫描一次端口
4. 建立 WebSocket 连接
5. 命令流转：Claude Code → MCP → 扩展 → Chrome API
6. Claude Code 关闭时，进程自动退出（通过检测 stdin）

保持更新

Browser MCP 由两部分组成，且两部分独立更新——扩展的更新方式取决于你的安装方式：

部分	安装方式	更新方式
MCP 服务	任意	**自动。**通过 npx @agent360/browser-mcp@latest 运行，因此每次 Claude Code 会话都会从 npm 获取最新版本。无需操作。
扩展	Chrome 网上应用店	**自动，但不会立即更新。**新版本首先要通过 Google 审核，通常需要 1-3 天；随后 Chrome 会在几小时内于后台获取更新。无需操作，但今天发布的修复不会在今天送达。
扩展	解压安装（npx … install 或手动解压 zip）	**手动。**Chrome 永远不会自动更新通过“加载已解压的扩展程序”安装的扩展。重新运行 npx @agent360/browser-mcp install，然后打开 chrome://extensions → Browser MCP → ↻ 重新加载。

**不确定自己安装的是哪种？**打开 chrome://extensions 并找到 Browser MCP。如果显示 "Loaded from /path/…"，说明是解压安装（需要手动更新）。如果没有这行文字，说明它来自 Chrome 网上应用店（自动更新）。

**想要免维护更新？**从 Chrome 网上应用店安装扩展，然后运行 claude mcp add --scope user browser-mcp -- npx @agent360/browser-mcp@latest 注册服务。此后，只要你的配置使用 @agent360/browser-mcp@latest，两部分都会自行保持最新。

故障排除

“Chrome 扩展未连接”

• 检查扩展是否已在 chrome://extensions 中加载
• 点击扩展弹出窗口 → “重新连接”
• 等待 2-3 秒进行端口扫描

截图失败

• 使用 Chrome Debugger API 获取当前会话自己的标签页（即使标签页未处于焦点状态也可运行）
• 从 1.29.1 开始，不再回退到截取当前可见的标签页：如果调试器无法生成画面，调用就会失败。（1.29.0 及更早版本可以回退到可见标签页。）运行 browser_reattach_debugger 并重试

在 SPA 上点击不起作用

• 尝试文本选择器：browser_click("text=Submit")
• 自动通过 Chrome Debugger API 使用真实鼠标事件

上传失败并显示“未获允许”

• 只有在 Agent360 Browser MCP 扩展中启用“允许访问文件网址”后，Chrome 才会将文件交给页面（chrome://extensions，Agent360 Browser MCP，详细信息）。从 Chrome 网上应用店安装时，此选项默认关闭
• 此开关还允许扩展将任何本地文件作为页面打开，因此是否启用由你决定；否则请自行附加文件
• 从 1.30.2 开始，交接过程中的“未获允许”错误会报告为 file-access-off，除非 Chrome 确认文件访问已开启

残留进程

• Claude Code 关闭时，进程会自动退出（通过 stdin 检测）
• 空闲超时：4 小时没有命令 → 自动退出
• 手动清理：lsof -i :9876-9895 | grep LISTEN

💡 一起塑造 Browser MCP

Browser MCP 以开源方式构建，并由使用它的人共同塑造。

浏览其他人的需求和作品

• 💡 愿望清单 → - 大家希望添加的功能
• 🎯 使用案例 → - 其他人构建的内容（LinkedIn ICP 抓取、供应商调研、日常运营，……）

30 秒内参与贡献

• 💡 许愿添加功能
• 🎯 分享使用案例
• 🐛 报告错误

或者直接询问 Claude——它了解 browser_about 工具；当你说“希望 browser-mcp 能……”或“分享我的 browser-mcp 使用案例”之类的话时，它会起草报告并提供链接，供你审核和提交。

如果它对你有用

Chrome 网上应用店会根据评分排名，而我们还没有评分——所以你的一句话比我们能写的任何内容都更有分量。如果它值得获得好评，请留下评价；如果不值得，也请如实说明。不需要注册，没有奖励，也没有任何门槛——我们目前只是完全没有任何反馈信号。

同一理念，覆盖 Mac 的其他部分

它能控制你的浏览器。Computer MCP 则能控制 macOS 上的其他一切——菜单、窗口、Dock，以及任何应用的辅助功能树——并秉持同样的原则：在写入截图之前，内存中的密码字段会被涂黑；写入操作须经过许可门槛；每个操作都会记录在仅追加的日志中。它默认在后台运行：除非你主动请求，否则不会提供可能接管屏幕的工具。

npx @agent360/computer-mcp · MIT · macOS。

隐私

这款工具旨在让你的浏览活动留在浏览器中。你和网页之间没有账户，也没有我们的服务器。

• 页面内容——工具从标签页读取的内容会发送到你配置的 MCP 客户端，仅此而已。我们永远看不到这些内容。
• Cookie、本地存储和令牌默认不会被复制到任何地方，服务也不会保存它们的副本——但这些数据可以被访问。有三个工具会直接读取它们（browser_get_cookies、browser_get_local_storage、browser_extract_token），另有两个工具会写入它们（browser_set_cookies、browser_set_local_storage），还有三个工具可以通过其他方式获取相同的数据：browser_execute_script 在页面中运行，可以读取 document.cookie；而 browser_get_page_content 和 browser_extract_list 会携带页面自身放入 DOM 的令牌。运行这些工具时，相应的值会像其他工具结果一样发送到你的 MCP 客户端，不会发送到其他地方，也绝不会发送给我们。
• **我们不收集任何信息。**扩展和服务都不会收集标识符、使用次数、崩溃报告或分析数据。
• Agent 自己生成的报告。browser_provide_feedback 会像其他工具结果一样将报告返回给你的 AI 客户端，并会尝试在你的设备上将每份新报告追加为一行，写入 ~/.browser-mcp/feedback.jsonl：内容包括时间、类型、工具、Agent 所述的情况、它尝试了什么以及最终奏效的办法、页面的来源和路径、版本号、简短诊断、已连接扩展的数量，以及用于跳过重复报告的指纹。对于 Agent 写下的三项内容（发生了什么、尝试了什么、哪些办法奏效），邮箱地址和长度为 6 个或更多字符的数字会先替换为 [email] 和 [number]，无论是在文件中还是返回的预填问题链接中都是如此；页面地址只保留来源和路径。服务不会提交报告。打开链接会将其内容发送到 GitHub；只有在你提交后才会创建问题。删除文件即可清除报告。
• 扩展与 MCP 客户端之间的桥接程序在同一台设备上的 localhost 运行；服务仅在你通过 BROWSER_MCP_CHECK_NPM=1 启用 npm 版本检查时才会访问网络。此桥接程序是本地且未经身份验证的：同一台设备上以你的身份运行的其他程序可以连接它。Browser MCP 无法保护你免受你已在运行的软件的影响。
• Agent 发送的 JavaScript（browser_execute_script、browser_select_frame）仅通过 Chrome 的 Debugger API（1.31）在 Agent 会话中的标签页内运行；它不属于扩展的一部分，且 Chrome 会显示扩展正在调试浏览器的提示。browser_list_tabs 会将会话中标签页的网址和标题返回给你的 MCP 客户端；Browser MCP 不会读取 Chrome 的历史记录。
• 你在扩展弹出窗口中设置的配置名称（1.31）和安装 ID 是用于选择 Chrome 配置文件的标签，而非凭据。扩展会以未签名的形式将它们发送给端口范围内的每个 Browser MCP 服务，同一台设备上的其他程序也可以使用相同名称。该 ID 是随机生成的，每个 Chrome 配置文件仅创建一次，并保存在扩展的本地存储中。二者都会出现在 browser_about 和 profile-* 错误答复中，因此会像其他工具答复一样发送给你的 Agent，进而发送给 Agent 使用的模型提供商。

完整政策：https://browsermcp.dev/privacy

许可证

MIT - Agent360