Browser MCP 是由 Agent360 开发的开源项目，它通过 Chrome 扩展程序与 MCP（Model Context Protocol）服务器的协作，使 Claude Code 能够控制用户真实的 Chrome 浏览器。该项目支持多会话并发（最多 10 个并发 AI 会话）、人工介入机制（2FA 验证码、凭证输入）以及内置的第三方服务集成（如 Stripe、HubSpot、Slack 等），总计提供 34 个浏览器自动化工具。资料来源：README.md:1-10

核心特性

Browser MCP 与其他浏览器自动化方案相比，具有以下独特优势：

资料来源：README.md:76-92

系统架构

整体架构

Browser MCP 由两个核心组件构成：Chrome 扩展程序（负责与浏览器 API 交互）和 MCP 服务器（负责与 Claude Code 通过标准输入/输出通信）。

graph TD
    subgraph Claude_Code["Claude Code"]
        A[用户请求]
    end
    
    subgraph MCP_Server["MCP Server (Node.js)"]
        B[stdio 通信]
        C[WebSocket 客户端]
        D[工具调度器]
    end
    
    subgraph Chrome_Extension["Chrome 扩展程序"]
        E[后台脚本 background.js]
        F[离屏文档 offscreen.js]
        G[弹出窗口 popup"]
        H[Chrome Debugger API"]
    end
    
    A --> B
    B --> D
    D --> C
    C <-->|WebSocket| F
    F --> E
    E --> H
    
    style Claude_Code fill:#f9f,color:#000
    style MCP_Server fill:#bbf,color:#000
    style Chrome_Extension fill:#bfb,color:#000

项目目录结构

browser-mcp/
├── extension/                      # Chrome 扩展程序（Manifest V3）
│   ├── background.js               # Service Worker — 所有浏览器自动化逻辑
│   ├── manifest.json               # 扩展配置与权限声明
│   ├── offscreen.js                # WebSocket 网桥（多端口扫描）
│   ├── popup.html/js               # 状态 UI — 会话、标签页、动作日志
│   └── icons/                      # 扩展图标资源
│
├── mcp-server/                     # MCP 服务器（Node.js）
│   ├── index.js                    # MCP 服务器 + WebSocket 客户端
│   ├── tools.js                    # 34 个工具定义
│   ├── bin/
│   │   └── cli.js                  # CLI 安装程序
│   └── package.json                # npm 包配置
│
├── docs/                           # 文档站（browsermcp.dev）
├── assets/                         # 演示视频与 GIF
├── CONTRIBUTING.md                 # 贡献指南
├── USE_CASES.md                    # 使用案例集
└── WISHLIST.md                     # 功能愿望单

资料来源：CONTRIBUTING.md:13-35

工作流程

Browser MCP 的通信流程涉及多个组件的协同工作：

1. 启动阶段：Claude Code 启动时，通过标准输入/输出（stdio）启动 MCP 服务器
2. 端口绑定：MCP 服务器在 9876-9885 范围内绑定第一个可用端口
3. 连接建立：扩展程序的离屏文档（offscreen.js）每 2 秒扫描可用端口，建立 WebSocket 连接
4. 命令执行：用户请求 → Claude Code → MCP 服务器 → WebSocket → 扩展程序 → Chrome APIs
5. 进程管理：通过 stdin 检测自动退出 Claude Code 关闭后的空闲进程，空闲超时 4 小时后自动退出

sequenceDiagram
    participant User as 用户
    participant Claude as Claude Code
    participant MCP as MCP Server
    participant Offscreen as offscreen.js
    participant Background as background.js
    participant Chrome as Chrome APIs

    User->>Claude: 发出浏览器控制请求
    Claude->>MCP: stdio 通信
    MCP->>Offscreen: WebSocket 连接
    Offscreen->>Background: 消息转发
    Background->>Chrome: Chrome Debugger API
    Chrome-->>Background: 执行结果
    Background-->>Offscreen: 响应数据
    Offscreen-->>MCP: WebSocket 响应
    MCP-->>Claude: stdio 响应
    Claude-->>User: 返回结果

资料来源：mcp-server/index.js:1-50

工具集详解

Browser MCP 提供 34 个工具，涵盖导航、内容获取、交互操作、状态等待、标签页管理等多个类别。

导航与内容获取

资料来源：mcp-server/tools.js:1-50

交互操作

资料来源：mcp-server/tools.js:51-120

状态等待

标签页与窗口管理

高级工具

资料来源：mcp-server/tools.js:121-200

安装与配置

快速安装（推荐方式）

npx @agent360/browser-mcp install

该命令完成以下操作：

1. 将 Chrome 扩展文件复制到 ~/.browser-mcp/extension/
2. 自动将 MCP 服务器添加到 Claude Code 配置
3. 在终端输出扩展文件夹的路径

资料来源：README.md:23-30

手动加载扩展程序

由于 Chrome 不允许扩展程序从 npm 自动安装，需要手动加载一次：

1. 在 Chrome 地址栏输入 chrome://extensions
2. 开启右上角的 开发者模式
3. 点击左上角的 加载已解压的扩展程序
4. 选择 ~/.browser-mcp/extension/ 文件夹
5. 重启 Claude Code 使 MCP 服务器配置生效

注意：各操作系统的扩展文件夹路径：

- macOS：~/.browser-mcp/extension/

- Windows：%USERPROFILE%\.browser-mcp\extension\

- Linux：~/.browser-mcp/extension/

资料来源：README.md:31-55

备用安装方式（无需 npm）

1. 从 GitHub Release 下载 browser-mcp-v1.16.1.zip
2. 解压到任意目录（如 ~/Downloads/browser-mcp-extension/）
3. 按照上述步骤 2-5 手动加载扩展程序
4. 手动配置 Claude Code，在 ~/.claude.json 中添加：

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

Chrome 网上应用店安装

从 Chrome 网上应用店直接安装，无需开发者模式，然后运行 npx @agent360/browser-mcp install --skip-extension 配置 Claude Code。

资料来源：README.md:56-70

使用场景

Browser MCP 适用于需要真实浏览器环境的各类自动化任务：

LinkedIn ICP 挖掘与外联

Claude 使用已有浏览器会话登录 LinkedIn，扫描搜索结果页面，基于职位、公司、行业识别理想客户档案（ICP），然后通过 HeyReach API 将符合条件的潜在客户推送到外联系统，AI 个性化外联自动启动销售对话。资料来源：USE_CASES.md:17-26

日常运营与调研

涵盖供应商调研、竞品价格对比、合作伙伴入职表单填写、支持工单的截图取证，以及从内部仪表板提取数据（无需付费购买 API）。资料来源：USE_CASES.md:34-40

其他应用场景

• 跨平台数据采集
• 表单自动填写
• 网页截图与文档生成
• 第三方平台 API 集成

自动更新机制

MCP 服务器通过 npx @agent360/browser-mcp@latest 运行，始终使用 npm 上的最新版本，无需手动 git pull 更新。扩展程序的更新则需要重新运行安装命令并重新加载扩展：

npx @agent360/browser-mcp install

然后在 chrome://extensions 中点击扩展程序卡片的重新加载按钮（🔄）。资料来源：mcp-server/README.md:95-102

故障排查

Chrome 扩展程序未连接

1. 检查扩展程序是否已加载在 chrome://extensions
2. 点击扩展程序弹出窗口中的 Reconnect 按钮
3. 等待 2-3 秒让端口扫描完成连接建立

截图功能失败

Browser MCP 使用 Chrome Debugger API 进行截图，即使标签页未获得焦点也能正常工作。如果调试器不可用，会自动回退到 captureVisibleTab。资料来源：mcp-server/README.md:104-107

单页应用（SPA）点击无效

尝试使用文本选择器：

browser_click("text=Submit")

系统会自动通过 Chrome Debugger API 发送真实的鼠标事件。资料来源：mcp-server/README.md:108-112

残留进程清理

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

社区参与

Browser MCP 采用开放式开发模式，欢迎各种形式的贡献：

也可以直接对 Claude Code 说 *"我希望 Browser MCP 能..."* 或 *"分享我的 Browser MCP 使用案例"*，Claude 会自动起草并提交。资料来源：CONTRIBUTING.md:36-55

参见

• 安装指南 — 详细的安装步骤与配置说明
• 工具参考 — 所有 34 个工具的完整参数说明
• 架构详解 — 系统组件与通信协议深度解析
• 故障排查 — 常见问题与解决方案
• 贡献指南 — 如何参与项目开发
• 愿望单 — 社区请求的功能特性
• 使用案例 — 用户分享的实际应用场景

概述

Browser MCP 是一个 Chrome 扩展与 MCP（Model Context Protocol）服务器的组合解决方案，允许 Claude Code 通过 34 个工具直接控制用户真实的 Chrome 浏览器。该项目的安装配置涉及三个核心组件的协同工作：MCP 服务器、Chrome 扩展以及 Claude Code 集成。资料来源：mcp-server/package.json:1-15

本指南将详细介绍 Browser MCP 的完整安装流程、配置选项以及常见问题的解决方案，帮助用户在 60 秒内完成从下载到运行的全过程。

系统要求

在开始安装之前，请确保您的环境满足以下最低要求：

资料来源：mcp-server/package.json:12

安装方式

Browser MCP 提供三种安装方式以适应不同用户的需求和环境条件。

推荐方式：npm 一键安装

这是最简单且推荐的安装方式，通过一条命令完成 MCP 服务器安装和 Chrome 扩展配置：

npx @agent360/browser-mcp install

此命令执行以下操作：

1. 将 Chrome 扩展文件复制到 ~/.browser-mcp/extension/ 目录
2. 自动检测并配置 Claude Code 的 MCP 服务器设置
3. 在终端输出扩展文件夹的完整路径供后续使用

资料来源：mcp-server/bin/cli.js:1-50

备选方式：手动下载安装

如果您无法使用 npm 或偏好手动管理安装包，可以选择手动下载方式：

1. 从 GitHub Releases 页面下载最新版本的 browser-mcp-v1.16.1.zip
2. 将压缩包解压到任意目录（如 ~/Downloads/browser-mcp-extension/）
3. 按照下一节的步骤手动加载扩展
4. 手动配置 Claude Code 的 MCP 服务器设置

资料来源：README.md:40-55

Chrome 应用商店安装

对于希望免去手动加载扩展步骤的用户，可以直接从 Chrome 应用商店一键安装：

从 Chrome Web Store 安装 →

此方式无需启用开发者模式，但仍需运行 npx @agent360/browser-mcp install --skip-extension 来配置 Claude Code。

资料来源：README.md:57-60

详细安装步骤

第一步：安装 MCP 服务器

运行安装命令后，终端将显示扩展文件夹路径。请记住此路径，稍后加载扩展时需要使用：

npx @agent360/browser-mcp install
# 输出示例：Extension files installed to: ~/.browser-mcp/extension/

资料来源：mcp-server/bin/cli.js:30-45

第二步：加载 Chrome 扩展

由于 Chrome 安全策略的限制，扩展无法自动安装到浏览器中，用户需要手动加载一次。之后扩展会自动保持更新。

#### 操作步骤

1. 打开 Chrome，在地址栏输入 chrome://extensions 并按回车
2. 在页面右上角启用 开发者模式 开关
3. 点击页面左上角的 "加载已解压的扩展程序" 按钮
4. 在文件选择对话框中导航到扩展文件夹：

1. 点击 "选择" 或 "打开" 确认

#### 快捷定位方法

• macOS：在文件选择对话框中按 Cmd+Shift+G，粘贴路径 ~/.browser-mcp/extension/，按回车
• Windows：在地址栏直接粘贴 %USERPROFILE%\.browser-mcp\extension\
• Linux：在路径字段输入 ~/.browser-mcp/extension/

加载成功后，Chrome 工具栏右上角将出现 Browser MCP 的图标。

资料来源：README.md:20-35

第三步：重启 Claude Code

完成扩展加载后，必须重启 Claude Code 以使 MCP 服务器配置生效。重启后，34 个浏览器自动化工具即可在对话中使用。

第四步：验证安装

安装完成后，可以通过以下方式验证：

1. 检查 Chrome 工具栏是否有 Browser MCP 图标
2. 在 Claude Code 中运行 browser_navigate 工具测试连接

browser_navigate("https://example.com")

1. 运行 browser_screenshot 验证截图功能正常

工作原理

Browser MCP 的安装配置涉及多个组件的协同工作。以下流程图展示了从启动到建立连接的完整过程：

graph TD
    A[Claude Code 启动] --> B[MCP 服务器通过 stdio 启动]
    B --> C[MCP 服务器绑定端口 9876-9885]
    C --> D[Chrome 扩展 offscreen 文档扫描端口]
    D --> E{找到可用端口?}
    E -->|是| F[建立 WebSocket 连接]
    E -->|否| D
    F --> G[命令流建立完成]
    G --> H[用户可执行浏览器工具]
    
    I[Claude Code 关闭] --> J[检测 stdin 关闭]
    J --> K[MCP 服务器进程退出]
    K --> L[4小时空闲超时自动退出]

组件交互说明

资料来源：mcp-server/index.js:1-30 资料来源：extension/manifest.json:1-20

配置说明

Claude Code 配置

安装命令会自动配置 Claude Code 的 ~/.claude.json 文件，添加类似以下内容：

{
  "mcpServers": {
    "browser-mcp": {
      "command": "node",
      "args": ["/path/to/mcp-server/index.js"]
    }
  }
}

资料来源：mcp-server/bin/cli.js:50-80

MCP 服务器配置

MCP 服务器使用以下默认配置参数：

服务器配置存储于安装过程中由 CLI 动态生成，不依赖静态配置文件。

资料来源：mcp-server/index.js:100-120

手动配置

如需手动配置 Claude Code，可编辑 ~/.claude.json：

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

资料来源：README.md:45-55

远程使用配置

根据社区反馈，当前的 Web 扩展无法直接检测远程 MCP 服务器，这是出于安全考虑的设计决策。然而，对于需要在局域网服务器上运行 MCP 网关的用户，社区已提供了解决方案。

社区方案概述

用户通过将 Browser MCP 的 MCP 服务器部署在远程服务器上，并配置 systemd 服务实现后台运行。浏览器端通过扩展与远程服务器建立连接。

此方案涉及：

• Linux 服务器上的 systemd 服务配置
• 网络端口转发或反向代理设置
• Chrome 扩展的自定义配置（可能需要修改源代码）

详细信息请参考社区讨论：Using browser-mcp remotely (linux + systemd solution)

自动更新机制

MCP 服务器更新

MCP 服务器通过 npx @agent360/browser-mcp@latest 运行，每次启动时自动获取 npm 注册表的最新版本，无需手动更新。

Chrome 扩展更新

扩展文件存储在本地 ~/.browser-mcp/extension/ 目录。更新方法：

1. 运行安装命令：npx @agent360/browser-mcp install
2. 打开 chrome://extensions
3. 点击 Browser MCP 扩展上的重新加载图标（🔄）

资料来源：README.md:65-70

常见问题排查

Chrome 扩展未连接

截图功能失败

Browser MCP 的截图功能使用 Chrome Debugger API，即使标签页不在前台也能正常工作。如果失败，扩展会自动降级到 captureVisibleTab 方法。

资料来源：README.md:75-80

单页应用点击无效

某些 SPA 框架的事件处理可能与标准 DOM 事件不同。建议使用文本选择器：

browser_click("text=提交")

此方式通过 Chrome Debugger API 发送真实的鼠标事件。

进程未正确退出

资料来源：README.md:80-90

卸载

如需完全卸载 Browser MCP：

1. 移除 Chrome 扩展

1. 打开 chrome://extensions
2. 找到 Agent360 Browser MCP 扩展
3. 点击 "移除" 并确认

2. 移除本地文件

rm -rf ~/.browser-mcp/

3. 移除 Claude Code 配置

编辑 ~/.claude.json，删除 mcpServers 中的 browser-mcp 配置项：

{
  "mcpServers": {
    // 删除以下部分
    "browser-mcp": { ... }
  }
}

4. 可选：卸载 npm 包

npm uninstall -g @agent360/browser-mcp

参见

• 工具列表 — 34 个浏览器自动化工具的完整参考
• 使用案例 — 用户分享的真实应用场景
• 愿望清单 — 功能请求列表
• 贡献指南 — 如何参与项目开发
• GitHub 仓库 — 官方源码仓库

架构概述

Browser MCP 采用双进程架构，通过 WebSocket 协议将 Chrome 扩展与 MCP 服务器连接起来。这种设计允许 Claude Code（作为 MCP 客户端）通过标准化的 Model Context Protocol 与用户的真实 Chrome 浏览器进行交互。

graph TD
    subgraph "Claude Code 进程"
        A["Claude Code<br/>(MCP 客户端)"]
    end
    
    subgraph "MCP 服务器进程"
        B["mcp-server/index.js<br/>(stdio 输入)"]
        C["WebSocket 客户端"]
    end
    
    subgraph "Chrome 浏览器进程"
        D["Chrome 扩展<br/>(Manifest V3)"]
        E["background.js<br/>(Service Worker)"]
        F["offscreen.js<br/>(WebSocket 桥接)"]
        G["Chrome APIs<br/>(Debugger/Tabs/Network)"]
    end
    
    A -->|"stdio"| B
    B -->|"动态端口 9876-9885"| C
    C -->|"WebSocket"| F
    E -->|"Chrome API 调用"| G
    F -->|"消息传递"| E
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style D fill:#e8f5e9
    style G fill:#fce4ec

核心设计目标

组件详解

MCP 服务器 (`mcp-server/`)

MCP 服务器是 Browser MCP 的核心枢纽，负责接收来自 Claude Code 的标准化 MCP 请求并将其转发至 Chrome 扩展。

graph LR
    subgraph "MCP 服务器核心模块"
        A["index.js<br/>主入口"]
        B["tools.js<br/>工具定义"]
        C["bin/cli.js<br/>安装程序"]
    end
    
    subgraph "依赖库"
        D["@modelcontextprotocol/sdk<br/>MCP 协议实现"]
        E["ws<br/>WebSocket 客户端"]
    end
    
    A -->|"定义工具"| B
    A -->|"npm install"| D
    A -->|"npm install"| E
    C -->|"调用"| A

#### 主入口文件 (index.js)

MCP 服务器使用 @modelcontextprotocol/sdk 提供的 Server 类实现，监听标准输入/输出（stdio）与 Claude Code 进行通信。

核心职责：

1. 协议处理：处理 ListToolsRequestSchema 和 CallToolRequestSchema 请求
2. WebSocket 连接管理：动态绑定可用端口（9876-9885 范围）
3. 命令转发：将工具调用通过 WebSocket 发送至扩展后台
4. 生命周期管理：检测 stdin 关闭实现自动退出

// 资料来源：mcp-server/index.js
const mcpServer = new Server(
  { name: 'agent360-browser', version: PKG_VERSION },
  { capabilities: { tools: {} } },
  { instructions: INSTRUCTIONS },
);

mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: TOOLS,
}));

mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;
  // WebSocket 转发逻辑
});

#### 工具定义 (tools.js)

tools.js 定义了所有暴露给 Claude Code 的浏览器自动化工具。截至 v1.16.1 版本，共提供 34 个工具。

工具分类：

#### CLI 安装程序 (bin/cli.js)

CLI 程序负责自动化安装流程，将扩展文件复制到用户目录并配置 Claude Code。

安装步骤：

1. 创建目录 ~/.browser-mcp/extension/
2. 复制扩展文件到目标目录
3. 更新 Claude Code 配置文件 ~/.claude.json 添加 MCP 服务器配置

# 资料来源：CONTRIBUTING.md
npx @agent360/browser-mcp install

Chrome 扩展 (`extension/`)

Chrome 扩展采用 Manifest V3 规范，是实际执行浏览器自动化操作的核心组件。

graph TD
    subgraph "Chrome 扩展组件"
        A["manifest.json<br/>扩展配置"]
        B["background.js<br/>Service Worker"]
        C["offscreen.js<br/>WebSocket 桥接"]
        D["popup.html/js<br/>状态 UI"]
    end
    
    B -->|"WebSocket 连接"| C
    B -->|"Chrome Debugger API"| E
    B -->|"Tabs API"| E
    B -->|"Network API"| E
    C -->|"端口扫描 9876-9885"| F["MCP 服务器"]
    
    subgraph "Chrome APIs"
        E["Chrome Debugger Protocol"]
    end

#### 后台脚本 (background.js)

background.js 是扩展的核心 Service Worker，负责：

1. 会话管理：维护多个并发的 AI 会话，每个会话对应一个颜色分组的标签页组
2. 工具执行：实现所有浏览器自动化工具的具体逻辑
3. 连接协调：通过 offscreen.js 与 MCP 服务器建立 WebSocket 连接

// 资料来源：extension/background.js
// 核心架构：基于颜色分组的会话隔离
const SESSION_COLORS = ['grey', 'blue', 'red', 'yellow', 'green', 'purple', 'cyan', 'orange', 'pink', 'brown'];

#### 离屏文档 (offscreen.js)

由于 Manifest V3 对 Service Worker 的限制，offscreen.js 作为独立的离屏文档运行，负责：

1. 端口扫描：每 2 秒扫描 9876-9885 范围内的可用端口
2. WebSocket 连接：与 MCP 服务器建立持久连接
3. 消息路由：双向传递 MCP 命令与响应

// 资料来源：extension/offscreen.js
// 端口扫描机制
const PORTS_TO_SCAN = [9876, 9877, 9878, 9879, 9880, 9881, 9882, 9883, 9884, 9885];
setInterval(scanPorts, 2000);

#### 扩展清单 (manifest.json)

Manifest V3 配置文件声明扩展的权限、脚本入口点和资源。

// 资料来源：extension/manifest.json
{
  "manifest_version": 3,
  "permissions": [
    "activeTab",
    "tabs",
    "debugger",
    "webNavigation",
    "storage"
  ],
  "host_permissions": ["<all_urls>"]
}

通信流程

命令执行完整流程

sequenceDiagram
    participant CC as Claude Code
    participant MCP as MCP Server
    participant OS as Offscreen.js
    participant BG as Background.js
    participant Chrome as Chrome APIs

    CC->>MCP: browser_navigate({url: "..."})
    Note over MCP: 解析工具名称和参数
    
    MCP->>MCP: 查询 methodMap 映射
    Note over MCP: browser_navigate → navigate
    
    MCP->>OS: WebSocket 发送 JSON-RPC
    Note over OS: 动态端口 (9876-9885)
    
    OS->>BG: chrome.runtime.sendMessage
    Note over BG: 内部消息传递
    
    BG->>Chrome: debugger.attach + DOM.getDocument
    Note over BG: Chrome Debugger Protocol
    
    BG->>BG: 执行浏览器自动化逻辑
    Note over BG: 标签页创建/导航/点击等
    
    Chrome-->>BG: 执行结果
    BG-->>OS: 返回结果
    OS-->>MCP: WebSocket 响应
    MCP-->>CC: MCP 响应格式

WebSocket 协议细节

MCP 服务器与扩展之间的通信采用 JSON-RPC 2.0 格式。

消息格式：

// 请求示例 (MCP Server → Extension)
{
  "jsonrpc": "2.0",
  "method": "navigate",
  "params": { "port": 1, "url": "https://example.com" }
}

// 响应示例 (Extension → MCP Server)
{
  "jsonrpc": "2.0",
  "result": { "ok": true, "tabId": 123 },
  "id": 1
}

端口分配策略：

会话管理机制

多会话架构

Browser MCP 支持最多 10 个并发的 AI 会话，每个会话在 Chrome 中对应一个独立的标签页组（Tab Group）。

graph TD
    subgraph "Chrome 窗口"
        subgraph "灰色标签组 (会话 1)"
            G1["标签 1"]
            G2["标签 2"]
        end
        
        subgraph "蓝色标签组 (会话 2)"
            B1["标签 3"]
            B2["标签 4"]
        end
        
        subgraph "红色标签组 (会话 N)"
            R1["标签 N"]
        end
    end
    
    subgraph "MCP 服务器"
        P1["端口 9876"]
        P2["端口 9877"]
        PN["端口 9885"]
    end
    
    P1 -->|"会话 1"| G1
    P2 -->|"会话 2"| B1
    PN -->|"会话 N"| R1

会话隔离策略

1. 颜色分组：每个会话关联一个唯一的颜色标识，便于视觉区分
2. 端口绑定：每个会话绑定独立的 WebSocket 端口
3. 标签页隔离：通过 chrome.tabs.group API 实现标签页物理隔离

// 资料来源：extension/background.js
// 会话创建逻辑
async function createSession(port) {
  const color = SESSION_COLORS[assignedTabs.size % SESSION_COLORS.length];
  const groupId = await chrome.tabs.group({ tabIds: tab.id });
  await chrome.tabGroups.update(groupId, { color });
}

生命周期管理

远程部署方案

架构限制

根据社区反馈（Issue #1），当前版本的 Web 扩展无法检测远程 MCP 服务器，这是出于安全考虑的主动设计决策。

systemd 服务方案

对于需要在 Linux 服务器上运行 MCP 网关的场景，可以采用以下架构：

graph LR
    subgraph "本地机器"
        A["Claude Code"]
        B["Chrome 浏览器"]
        C["Browser MCP 扩展"]
    end
    
    subgraph "远程服务器"
        D["MCP Gateway<br/>(systemd 服务)"]
        E["端口 9876-9885"]
    end
    
    A -->|"stdio"| D
    C -->|"WebSocket<br/>远程连接"| D
    
    style D fill:#fff3e0
    style E fill:#e8f5e9

systemd 服务配置示例：

# /etc/systemd/system/browser-mcp-gateway.service
[Unit]
Description=Browser MCP Gateway
After=network.target

[Service]
Type=simple
User=mcp-user
WorkingDirectory=/opt/browser-mcp
ExecStart=/usr/bin/node mcp-server/index.js
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

配置 WebSocket 端口范围：

扩展默认扫描本地端口 9876-9885。如需连接远程服务器，需要修改 offscreen.js 中的连接逻辑。

工具执行架构

工具调用映射

每个 MCP 工具通过 methodMap 映射到扩展中的具体处理函数：

// 资料来源：mcp-server/index.js
const methodMap = {
  browser_navigate: 'navigate',
  browser_get_page_content: 'get_page_content',
  browser_screenshot: 'screenshot',
  browser_click: 'click',
  browser_fill: 'fill',
  // ...
};

Chrome Debugger Protocol 集成

Browser MCP 大量使用 Chrome Debugger Protocol 实现高级浏览器自动化：

graph TD
    A["工具调用"] --> B["background.js"]
    B --> C{"工具类型"}
    
    C -->|"DOM 操作"| D["DOM.getDocument"]
    C -->|"网络监控"| E["Network.enable"]
    C -->|"截图"| F["Page.captureScreenshot"]
    C -->|"截图(备用)"| G[" tabs.captureVisibleTab"]
    
    D --> H["DOM.querySelector"]
    D --> I["DOM.dispatchEvent"]
    
    style F fill:#e8f5e9
    style G fill:#fff3e0

截图功能实现

截图功能支持两种实现方式，根据环境自动降级：

// 资料来源：extension/background.js
// 截图处理逻辑
async function screenshot(args, sender) {
  try {
    // 优先使用 Debugger API
    await debugger.attach('tab');
    const result = await sendCommand('Page.captureScreenshot');
    return { base64: result.data, format: 'png' };
  } catch (e) {
    // 降级到 tabs API
    const dataUrl = await tabs.captureVisibleTab();
    return { base64: dataUrl.split(',')[1], format: 'png' };
  }
}

注意：社区反馈（Issue #2）建议截图工具应支持直接保存到指定文件路径，而非仅返回 base64 数据。

安全性考虑

权限模型

数据隔离

1. 会话隔离：通过标签页组颜色实现视觉和逻辑隔离
2. 凭证存储：使用 chrome.storage 加密存储凭据
3. 进程分离：MCP 服务器与 Chrome 扩展运行在不同进程

相关配置

环境要求

依赖关系

参见

• 安装指南 - 完整的安装和配置流程
• 工具参考 - 所有 34 个工具的详细说明
• 使用案例 - 真实用户场景展示
• 故障排除 - 常见问题解决方案
• WISHLIST.md - 功能需求列表

核心概念

Browser MCP 的多会话管理基于以下核心概念：

• 会话（Session）：一次 MCP 服务器实例，代表一个独立的 AI 自动化任务
• 标签页组（Tab Group）：Chrome 原生功能，每个会话的标签页会被归入同一个颜色标记的组
• 端口分配（Port Allocation）：每个会话绑定到 9876-9885 范围内的唯一端口
• WebSocket 通道：MCP 服务器通过 WebSocket 与扩展通信，而非传统的 Chrome 调试协议直连

架构设计

系统组件

graph TB
    subgraph "Claude Code 实例"
        A1["Claude Code Session 1<br/>(MCP Server Port 9876)"]
        A2["Claude Code Session 2<br/>(MCP Server Port 9877)"]
        A3["Claude Code Session N<br/>(MCP Server Port 98XX)"]
    end
    
    subgraph "WebSocket 连接层"
        WS1["WebSocket Client<br/>ws://localhost:9876"]
        WS2["WebSocket Client<br/>ws://localhost:9877"]
        WS3["WebSocket Client<br/>ws://localhost:98XX"]
    end
    
    subgraph "Browser MCP Extension"
        OS["Offscreen Document<br/>端口扫描 (2s间隔)"]
        SW["Service Worker<br/>会话路由 & 标签页管理"]
        BG["Chrome APIs<br/>Debugger / Tabs / TabGroups"]
    end
    
    subgraph "Chrome Browser"
        TG1["Session 1 Tab Group<br/>🔴 红色"]
        TG2["Session 2 Tab Group<br/>🔵 蓝色"]
        TG3["Session N Tab Group<br/>🟢 绿色"]
    end
    
    A1 --> WS1 --> OS
    A2 --> WS2 --> OS
    A3 --> WS3 --> OS
    OS <--> SW
    SW --> BG
    BG --> TG1
    BG --> TG2
    BG --> TG3

通信流程

1. 会话启动：Claude Code 启动时通过 stdio 启动 MCP 服务器进程
2. 端口绑定：MCP 服务器在 9876-9885 范围内查找第一个可用端口并绑定
3. 端口扫描：扩展的 Offscreen Document 每 2 秒扫描一次可用端口
4. 连接建立：发现端口后建立 WebSocket 连接，完成会话绑定
5. 命令执行：工具调用通过 MCP 协议 → WebSocket → Service Worker → Chrome APIs
6. 会话隔离：每个会话的标签页自动归入对应颜色标记的 Tab Group

会话生命周期

启动流程

sequenceDiagram
    participant CC as Claude Code
    participant MCP as MCP Server
    participant OS as Offscreen Document
    participant SW as Service Worker
    participant Chrome as Chrome Browser

    CC->>MCP: 启动进程 (stdio)
    MCP->>MCP: 绑定端口 9876
    Note over MCP: lastActivity = Date.now()
    
    loop 每2秒
        OS->>OS: 扫描端口 9876-9885
        OS->>MCP: 发现可用端口
        OS->>SW: 建立 WebSocket 连接
    end
    
    SW->>Chrome: 创建 Tab Group (颜色分配)
    MCP-->>CC: MCP 协议就绪

关闭流程

Browser MCP 支持三种自动关闭机制，资料来源：mcp-server/index.js:80-85

// 空闲超时：4小时无命令自动退出
// stdin 检测：Claude Code 关闭时自动退出
// 进程管理：端口冲突时自动重试下一个端口

端口分配策略

端口范围

Browser MCP 使用端口范围 9876-9885 进行会话分配，资料来源：extension/offscreen.js

graph LR
    A["端口 9876"] --> B["会话 1"]
    C["端口 9877"] --> D["会话 2"]
    E["端口 9878"] --> F["会话 3"]
    G["..."] --> H["..."]
    I["端口 9885"] --> J["会话 10"]

分配规则

标签页组管理

颜色分配机制

Browser MCP 使用 Chrome 原生 Tab Group API 为每个会话分配唯一颜色，资料来源：extension/background.js

const COLORS = ['grey', 'blue', 'red', 'yellow', 'green', 'pink', 'purple', 'cyan', 'orange'];

标签页隔离

每个会话创建的标签页会自动归入对应的 Tab Group，实现以下隔离：

• 视觉隔离：不同会话的标签页用颜色区分，便于在 Chrome 界面识别
• 标签隔离：可折叠/展开整个标签页组，避免标签栏混乱
• 操作隔离：会话间不会误操作彼此的标签页

WebSocket 桥接

Offscreen Document 职责

扩展使用 Offscreen Document（离屏文档）作为 WebSocket 客户端，资料来源：extension/offscreen.js

graph TD
    A["端口扫描"] --> B{"找到 MCP Server?"}
    B -->|否| A
    B -->|是| C["建立 WebSocket"]
    C --> D{"连接成功?"}
    D -->|否| A
    D -->|是| E["保存连接"]
    E --> F["消息循环"]
    F --> G{"收到消息?"}
    G -->|是| H["转发至 Service Worker"]
    H --> F
    G -->|否| F

消息格式

WebSocket 消息采用 JSON 格式，资料来源：mcp-server/index.js 和 extension/background.js

// MCP 请求格式
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "browser_navigate",
    "arguments": { "url": "https://example.com" }
  }
}

// MCP 响应格式
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "Navigation successful" }]
  }
}

配置与使用

自动配置

使用 npx @agent360/browser-mcp install 安装时，会自动配置所有会话相关设置，资料来源：mcp-server/bin/cli.js

npx @agent360/browser-mcp install

该命令会：

1. 复制扩展文件到 ~/.browser-mcp/extension/
2. 在 Claude Code 配置中添加 MCP 服务器
3. 配置 WebSocket 连接参数

手动配置

对于高级用户，可手动配置多会话，资料来源：mcp-server/index.js

// ~/.claude.json 或项目 .mcp.json
{
  "mcpServers": {
    "browser-mcp-1": {
      "command": "npx",
      "args": ["@agent360/browser-mcp"]
    },
    "browser-mcp-2": {
      "command": "npx",
      "args": ["@agent360/browser-mcp"]
    }
  }
}

环境变量

远程使用场景

⚠️ 安全注意：Web 扩展出于安全考虑不会检测远程 MCP 服务器，资料来源：社区讨论 #1

社区用户提出了远程使用需求：在 Linux 服务器上运行 MCP 网关，本地浏览器连接。解决方案包括：

1. 使用 systemd 在服务器上托管 MCP 服务
2. 通过本地网络暴露端口供浏览器扩展连接
3. 配置反向代理或 SSH 隧道

# 示例：systemd 服务配置
[Unit]
Description=Browser MCP Server
After=network.target

[Service]
ExecStart=/usr/bin/node /path/to/mcp-server/index.js
Environment="PORT=9876"
Restart=on-failure

[Install]
WantedBy=multi-user.target

故障排除

连接问题

进程残留

# 查找残留进程
lsof -i :9876-9885 | grep LISTEN

# 终止指定进程
kill <PID>

# 或使用 Browser MCP 内置清理
npx @agent360/browser-mcp cleanup

截图工具优化

💡 社区建议：截图工具应支持文件路径参数直接保存，而非传递 base64，资料来源：社区讨论 #2

当前 browser_screenshot 工具支持 path 参数，可直接指定保存路径：

// 使用示例
browser_screenshot({ path: "/path/to/screenshot.png" })

限制与注意事项

相关工具

Browser MCP 提供以下与会话管理相关的工具：

参见

• 安装指南 - 完整的安装步骤
• 工具列表 - 所有 34 个工具的详细说明
• 故障排除 - 常见问题解答
• 贡献指南 - 如何参与项目开发

概述

导航与内容工具是 Browser MCP 提供的一组核心工具，用于在浏览器中进行网页导航和内容提取。这些工具使 Claude Code 能够控制用户的真实 Chrome 浏览器，访问网页、获取页面内容、截取屏幕截图以及执行自定义 JavaScript 代码。

Browser MCP 的导航与内容工具具有以下特点：

• 真实浏览器会话：使用用户已有的 Chrome 浏览器，保留登录状态和 Cookie
• 多种输出格式：支持文本、HTML 原始格式以及 base64 编码的图片
• 灵活的导航策略：支持在当前标签页导航或打开新标签页
• 强大的脚本执行能力：可在页面上下文中执行任意 JavaScript 代码

工具列表

架构与数据流

graph TD
    A[Claude Code] -->|MCP协议| B[MCP Server<br/>mcp-server/index.js]
    B -->|WebSocket| C[Extension Offscreen<br/>extension/offscreen.js]
    C -->|Chrome API| D[Extension Background<br/>extension/background.js]
    D -->|Chrome Debugger API| E[用户Chrome浏览器]
    
    F[工具定义<br/>mcp-server/tools.js] -->|TOOLS数组| B
    
    G[methodMap映射<br/>mcp-server/index.js] -->|方法名转换| C
    
    style A fill:#e1f5fe
    style E fill:#fff3e0
    style B fill:#f3e5f5

通信流程

1. MCP请求接收：Claude Code 通过标准输入/输出（stdio）发送 MCP 请求到 MCP 服务器
2. 工具方法映射：index.js 中的 methodMap 将 browser_* 工具名称映射为浏览器操作方法名
3. WebSocket转发：MCP 服务器通过 WebSocket 将请求转发到扩展的离屏文档（offscreen document）
4. 浏览器执行：background.js 中的 Service Worker 通过 Chrome Debugger API 执行实际的浏览器操作
5. 结果返回：执行结果沿原路径返回，最终以 MCP 协议格式输出给 Claude Code

browser_navigate

功能说明

browser_navigate 工具用于将活动浏览器标签页导航到指定 URL。这是 Browser MCP 中最基础的导航工具，支持两种导航模式：

• 复用当前标签页（默认）：在同一标签页中打开新页面，不会产生标签页泛滥
• 新标签页模式：new_tab=true 时，在新标签页中打开页面，保留当前页面

输入参数

使用示例

// 导航到网页
await browser_navigate({ url: "https://example.com" })

// 在新标签页中打开
await browser_navigate({ 
  url: "https://docs.example.com", 
  new_tab: true 
})

实现细节

该工具在 background.js 中通过 Chrome Tabs API 实现。核心逻辑如下：

case 'navigate': {
  const tab = await getSessionTab(port);
  if (args.new_tab) {
    await chrome.tabs.create({ url: args.url, active: true });
  } else {
    await chrome.tabs.update(tab.id, { url: args.url });
    await waitForLoad(tab.id);
  }
  return { ok: true, url: args.url };
}

资料来源：extension/background.js

browser_get_page_content

功能说明

browser_get_page_content 工具用于获取当前页面的内容，支持两种输出格式：纯文本和完整 HTML。该工具对于网页内容提取、数据采集和页面分析非常有用。

输入参数

使用示例

// 获取页面纯文本内容
const text = await browser_get_page_content({ format: "text" });

// 获取页面完整HTML
const html = await browser_get_page_content({ format: "html" });

实现细节

该工具通过 Chrome Debugger Protocol 的 Page.getResourceContent 和 Runtime.evaluate 方法实现。文本模式下会移除所有 HTML 标签，仅保留可见文本内容。

case 'get_page_content': {
  const tab = await getSessionTab(port);
  const result = await sendToDebugger(tab.id, 'Runtime.evaluate', {
    expression: args.format === 'html' 
      ? 'document.documentElement.outerHTML' 
      : 'document.body.innerText',
    returnByValue: true,
  });
  return { ok: true, content: result.result.value };
}

资料来源：extension/background.js

browser_screenshot

功能说明

browser_screenshot 工具用于截取当前可见区域的屏幕截图。该工具使用 Chrome Debugger API 实现，即使标签页不在前台焦点也能正常工作，解决了传统截图方法的局限性。

输入参数

使用示例

// 获取base64编码的PNG截图
const screenshot = await browser_screenshot({});

// 保存截图到指定路径
await browser_screenshot({ path: "/tmp/page-screenshot.png" });

输出格式

实现细节

工具优先使用 Chrome Debugger API 的 Page.captureScreenshot 方法，该方法即使在标签页未获得焦点时也能正常工作。如果调试器不可用，则回退到 chrome.tabs.captureVisibleTab API。

case 'screenshot': {
  const tab = await getSessionTab(port);
  try {
    const result = await sendToDebugger(tab.id, 'Page.captureScreenshot', {
      format: 'png',
    });
    const base64 = result.data;
    
    if (args.path) {
      const buffer = Buffer.from(base64, 'base64');
      await fs.writeFileSync(args.path, buffer);
      return { ok: true, path: args.path };
    }
    return { ok: true, base64 };
  } catch (e) {
    // 回退逻辑...
  }
}

资料来源：extension/background.js

社区反馈

社区用户提出了一个关于截图工具的功能请求：希望截图工具能够直接接受文件路径参数并保存到该路径，而不是返回 base64 编码。这一功能已在当前版本中实现，用户可以指定 path 参数直接保存截图文件。

browser_execute_script

功能说明

browser_execute_script 工具允许在当前页面的上下文中执行任意 JavaScript 代码。这为 Browser MCP 提供了极大的灵活性，可以实现工具未直接提供的自定义功能，如操作 Web Components、读取特定 DOM 元素、执行自定义动画等。

输入参数

使用示例

// 获取页面标题
const title = await browser_execute_script({
  code: "document.title"
});

// 操作DOM元素
await browser_execute_script({
  code: "document.querySelector('.modal').style.display = 'none'"
});

// 读取localStorage
const userData = await browser_execute_script({
  code: "JSON.parse(localStorage.getItem('user'))"
});

实现细节

该工具使用 Chrome Debugger Protocol 的 Runtime.evaluate 方法执行代码，并设置 returnByValue: true 以便返回可序列化的结果。

case 'execute_script': {
  const tab = await getSessionTab(port);
  const result = await sendToDebugger(tab.id, 'Runtime.evaluate', {
    expression: args.code,
    returnByValue: true,
  });
  return { ok: true, result: result.result.value };
}

资料来源：extension/background.js

注意事项

• 执行环境是页面的主框架（main frame），不包括 iframe
• 无法访问扩展程序的上下文，只能访问网页的 JavaScript 上下文
• 返回值必须是可序列化的 JSON 类型
• 长时间运行的脚本可能会超时

methodMap 映射机制

Browser MCP 采用命名空间隔离设计，MCP 工具名称（browser_*）与浏览器操作方法名不同。methodMap 定义了两者之间的映射关系：

const methodMap = {
  browser_navigate: 'navigate',
  browser_get_page_content: 'get_page_content',
  browser_screenshot: 'screenshot',
  browser_execute_script: 'execute_script',
  // ...其他工具
};

资料来源：mcp-server/index.js

这种设计使得工具命名空间清晰，便于扩展和维护。

与其他工具的协作

导航与内容工具通常与其他 Browser MCP 工具配合使用，形成完整的自动化工作流：

graph LR
    A[browser_navigate] --> B[browser_get_page_content]
    B --> C[内容分析]
    C --> D[browser_click]
    C --> E[browser_fill]
    C --> F[browser_execute_script]
    
    A --> G[browser_screenshot]
    G --> H[视觉验证]

例如，一个典型的数据采集工作流可能是：

1. browser_navigate — 导航到目标网站
2. browser_click / browser_fill — 与页面交互
3. browser_wait — 等待内容加载
4. browser_get_page_content — 提取数据
5. browser_screenshot — 截图存档

错误处理与故障排除

常见错误场景

扩展连接状态

Browser MCP 使用 WebSocket 进行进程间通信。如果扩展未正确连接，MCP 服务器会在日志中提示"Chrome extension not connected"。可以通过扩展弹窗中的"Reconnect"按钮重新建立连接。

扩展开发指南

添加新的导航/内容工具

1. 在 mcp-server/tools.js 的 TOOLS 数组中添加工具定义
2. 在 extension/background.js 中添加对应的 case 处理逻辑
3. 在 mcp-server/index.js 的 methodMap 中添加映射关系

// 1. mcp-server/tools.js
{
  name: 'browser_my_tool',
  description: '工具描述',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string', description: '参数描述' }
    }
  }
}

// 2. extension/background.js
case 'my_tool': {
  const tab = await getSessionTab(port);
  // 实现逻辑
  return { ok: true };
}

// 3. mcp-server/index.js
browser_my_tool: 'my_tool',

参见

• 交互工具 — 点击、填充、键盘事件等交互工具
• 会话管理 — 多会话支持和标签页组管理
• 架构概览 — Browser MCP 整体架构
• 安装指南 — 完整安装配置流程
• 故障排除 — 常见问题与解决方案

概述

交互操作工具是 Browser MCP 的核心功能模块，提供了 34 种用于控制浏览器进行人机交互的工具。这些工具通过 Chrome Debugger API 实现真实的用户交互行为，包括点击、输入、键盘操作、滚动、悬停、下拉菜单选择以及对话框处理等。资料来源：mcp-server/tools.js:1-50

与传统的无头浏览器自动化工具不同，Browser MCP 的交互操作工具直接控制用户真实的 Chrome 浏览器，这意味着：

• 会话保持：用户的登录状态、Cookie 和本地存储会被保留
• 人机交互支持：可以处理需要用户参与的 2FA、CAPTCHA 和凭据输入场景
• 真实事件模拟：通过 Chrome Debugger API 发送真实的鼠标和键盘事件，而非模拟事件

交互操作工具采用选择器系统，支持 CSS 选择器、文本选择器和复合选择器语法，提供了灵活的页面元素定位能力。资料来源：README.md:85-95

架构设计

组件交互流程

交互操作工具的架构涉及三个主要组件之间的通信：

graph TD
    A["Claude Code<br/>MCP 客户端"] -->|"stdio"| B["MCP Server<br/>mcp-server/index.js"]
    B -->|"WebSocket<br/>端口 9876-9885"| C["Chrome Extension<br/>offscreen.js"]
    C -->|"Chrome Debugger API"| D["用户 Chrome 浏览器"]
    
    B -.->|调度方法| E["background.js<br/>background.ts"]
    C -.->|port 连接| E
    
    style A fill:#e1f5fe
    style D fill:#fff3e0
    style B fill:#f3e5f5
    style C fill:#e8f5e8

工具调度流程

当 Claude Code 调用一个交互操作工具时，系统会执行以下调度流程：

sequenceDiagram
    participant Claude as Claude Code
    participant MCP as MCP Server
    participant Offscreen as offscreen.js
    participant BG as background.js
    participant Chrome as Chrome 浏览器

    Claude->>MCP: browser_click({selector: "text=提交"})
    MCP->>MCP: 查找方法映射
    MCP->>Offscreen: WebSocket 发送方法调用
    Offscreen->>BG: chrome.runtime.sendMessage
    BG->>Chrome: Chrome Debugger API
    Chrome-->>BG: 操作结果
    BG-->>Offscreen: 响应消息
    Offscreen-->>MCP: WebSocket 响应
    MCP-->>Claude: 返回结果

资料来源：mcp-server/index.js:40-80

工具分类

交互操作工具可分为以下几大类：

资料来源：mcp-server/tools.js:1-200

交互操作工具详解

browser_click 点击

在页面中点击指定元素。

{
  name: 'browser_click',
  description: 'Click on an element. Supports CSS selectors, text selectors, and combined selectors like button:text(Next).',
  inputSchema: {
    type: 'object',
    properties: {
      selector: { 
        type: 'string', 
        description: 'CSS selector, text selector (text=Button Text), or combined selector (button:text(Next))' 
      },
      button: { 
        type: 'string', 
        enum: ['left', 'middle', 'right'],
        description: 'Mouse button to use (default: left)' 
      },
      double: { 
        type: 'boolean', 
        description: 'Perform double-click instead of single click (default: false)' 
      },
      modifier: {
        type: 'string',
        description: 'Keyboard modifier: Control, Shift, Alt, Meta, or combinations like Control+Shift'
      },
      x: { type: 'number', description: 'X coordinate override' },
      y: { type: 'number', description: 'Y coordinate override' },
    },
    required: ['selector'],
  },
}

#### 选择器类型

资料来源：mcp-server/tools.js:70-110

browser_fill 填充输入

填充输入字段内容。

{
  name: 'browser_fill',
  description: 'Fill an input field or contenteditable element. Works on CSP-strict sites.',
  inputSchema: {
    type: 'object',
    properties: {
      selector: { 
        type: 'string', 
        description: 'CSS selector, text selector, or combined selector for the input field' 
      },
      value: { 
        type: 'string', 
        description: 'Value to fill into the field' 
      },
      press_enter: { 
        type: 'boolean', 
        description: 'Press Enter key after filling (default: false)' 
      },
    },
    required: ['selector', 'value'],
  },
}

特殊功能：

• 支持 <input>、<textarea> 和 contenteditable 元素
• 在 CSP 严格站点也能正常工作（通过 Chrome Debugger API 实现）
• 可选择性地在填充后按下 Enter 键

资料来源：mcp-server/tools.js:110-140

browser_press_key 键盘按键

模拟键盘按键操作。

{
  name: 'browser_press_key',
  description: 'Press keyboard keys including Enter, Tab, Escape, Backspace, and modifier combinations.',
  inputSchema: {
    type: 'object',
    properties: {
      key: { 
        type: 'string', 
        description: 'Key to press: Enter, Tab, Escape, Space, Backspace, ArrowUp, ArrowDown, etc.' 
      },
      modifier: {
        type: 'string',
        description: 'Modifier keys: Control, Shift, Alt, Meta (can combine with +)'
      },
      selector: {
        type: 'string',
        description: 'Optional: focus specific element before pressing key'
      },
    },
    required: ['key'],
  },
}

支持的修饰键组合：

• Control+A：全选
• Control+C：复制
• Control+V：粘贴
• Shift+Tab：反向切换焦点
• Control+Shift+T：恢复关闭的标签页（Chrome 快捷键）

browser_scroll 滚动

滚动页面或滚动到指定元素。

{
  name: 'browser_scroll',
  description: 'Scroll the page or scroll to a specific element.',
  inputSchema: {
    type: 'object',
    properties: {
      selector: { 
        type: 'string', 
        description: 'Element to scroll into view (optional)' 
      },
      direction: { 
        type: 'string', 
        enum: ['up', 'down', 'left', 'right'],
        description: 'Direction to scroll (default: down)' 
      },
      amount: { 
        type: 'number', 
        description: 'Scroll amount in pixels (default: 300)' 
      },
      into_view: {
        type: 'boolean',
        description: 'Whether to scroll element into center of viewport (default: true)'
      },
    },
  },
}

browser_wait 等待

等待元素出现或页面条件满足。

{
  name: 'browser_wait',
  description: 'Wait for an element to appear or a specific condition.',
  inputSchema: {
    type: 'object',
    properties: {
      selector: { 
        type: 'string', 
        description: 'CSS selector or text selector to wait for' 
      },
      state: { 
        type: 'string', 
        enum: ['attached', 'detached', 'visible', 'hidden'],
        description: 'Element state to wait for (default: visible)' 
      },
      timeout: { 
        type: 'number', 
        description: 'Timeout in milliseconds (default: 30000)' 
      },
    },
    required: ['selector'],
  },
}

等待状态说明：

browser_hover 悬停

鼠标悬停在元素上，用于触发工具提示、下拉菜单等。

{
  name: 'browser_hover',
  description: 'Hover over an element to trigger tooltips, dropdowns, or hover states.',
  inputSchema: {
    type: 'object',
    properties: {
      selector: { 
        type: 'string', 
        description: 'CSS selector or text selector for the element to hover over' 
      },
    },
    required: ['selector'],
  },
}

browser_select_option 下拉菜单选择

选择 <select> 元素或自定义下拉菜单的选项。

{
  name: 'browser_select_option',
  description: 'Select option(s) from native select elements and custom dropdowns (Angular Material, React Select).',
  inputSchema: {
    type: 'object',
    properties: {
      selector: { 
        type: 'string', 
        description: 'Select element selector or label' 
      },
      value: { 
        type: 'string', 
        description: 'Option value or text to select' 
      },
      multiple: { 
        type: 'boolean', 
        description: 'Select multiple options (default: false)' 
      },
    },
    required: ['selector', 'value'],
  },
}

支持的框架：

• 原生 <select> 元素
• Angular Material 下拉菜单
• React Select 组件
• 其他自定义下拉组件

browser_set_combobox 自动完成组合框

处理带自动完成功能的组合框，输入查询后从建议列表中选择。

{
  name: 'browser_set_combobox',
  description: 'Type into an autocomplete/combobox, wait for filtered listbox, and click an option.',
  inputSchema: {
    type: 'object',
    properties: {
      selector: { 
        type: 'string', 
        description: 'Combobox input selector' 
      },
      value: { 
        type: 'string', 
        description: 'Value to type' 
      },
      option: { 
        type: 'string', 
        description: 'Exact option text to click from dropdown (supports text= prefix)' 
      },
    },
    required: ['selector', 'value', 'option'],
  },
}

工作流程：

1. 在组合框中输入查询值
2. 等待筛选后的列表框出现
3. 从列表中选择匹配的选项

browser_handle_dialog 对话框处理

接受或拒绝浏览器对话框（alert、confirm、prompt）。

{
  name: 'browser_handle_dialog',
  description: 'Accept or dismiss browser dialogs (alert, confirm, prompt).',
  inputSchema: {
    type: 'object',
    properties: {
      accept: { 
        type: 'boolean', 
        description: 'Accept the dialog (true) or dismiss it (false, default: true)' 
      },
      prompt_text: { 
        type: 'string', 
        description: 'Text to enter in prompt dialogs (ignored for alert/confirm)' 
      },
    },
  },
}

browser_ask_user 用户询问

向用户请求信息，支持 2FA、CAPTCHA 和凭据输入。

{
  name: 'browser_ask_user',
  description: 'Ask the user for input (2FA codes, CAPTCHA solutions, credentials, confirmations).',
  inputSchema: {
    type: 'object',
    properties: {
      question: { 
        type: 'string', 
        description: 'Question to display to the user' 
      },
      type: { 
        type: 'string', 
        enum: ['text', 'password', 'confirm'],
        description: 'Input type expected from user' 
      },
      default_value: {
        type: 'string',
        description: 'Default value for text/password input'
      },
    },
    required: ['question'],
  },
}

使用场景：

• 需要 TOTP 双因素认证码
• 需要人工解决 CAPTCHA
• 需要用户提供登录凭据
• 需要用户确认危险操作

资料来源：mcp-server/tools.js:140-200

使用模式与最佳实践

基础交互模式

典型的页面交互流程：

// 1. 导航到目标页面
browser_navigate({ url: "https://example.com/login" })

// 2. 等待登录表单加载
browser_wait({ selector: "#username", state: "visible" })

// 3. 填充登录信息
browser_fill({ selector: "#username", value: "[email protected]" })
browser_fill({ selector: "#password", value: "secretpassword" })

// 4. 点击登录按钮
browser_click({ selector: "text=登录" })

// 5. 等待登录完成
browser_wait({ selector: "text=欢迎回来", state: "visible" })

处理复杂下拉菜单

对于 Angular Material 等框架的自定义下拉菜单：

// 点击下拉菜单触发器
browser_click({ selector: "mat-select[formcontrolname=status]" })

// 等待选项列表出现
browser_wait({ selector: "mat-option", state: "visible" })

// 选择所需选项
browser_click({ selector: "mat-option:text(已完成)" })

处理需要用户参与的流程

// 检测到需要 2FA
browser_ask_user({
  question: "请输入您手机上收到的验证码",
  type: "text"
})
// 返回用户输入的验证码后继续
browser_fill({ selector: "#totp-code", value: "123456" })
browser_click({ selector: "text=验证" })

资料来源：README.md:60-85

故障排除

点击未生效

输入未写入

滚动问题

常见错误处理

// 使用 try-catch 处理超时
try {
  await browser_wait({ 
    selector: ".loading-complete", 
    state: "visible", 
    timeout: 5000 
  })
} catch (error) {
  console.log("等待超时，页面可能加载失败")
  browser_screenshot({ path: "/tmp/debug.png" })
}

方法映射机制

MCP Server 使用方法映射表将工具名称转换为扩展端的处理方法：

const methodMap = {
  browser_navigate: 'navigate',
  browser_get_page_content: 'get_page_content',
  browser_screenshot: 'screenshot',
  browser_execute_script: 'execute_script',
  browser_click: 'click',
  browser_fill: 'fill',
  browser_wait: 'wait',
  browser_press_key: 'press_key',
  browser_scroll: 'scroll',
  browser_hover: 'hover',
  browser_select_option: 'select_option',
  browser_handle_dialog: 'handle_dialog',
  browser_ask_user: 'ask_user',
};

资料来源：mcp-server/index.js:80-120

扩展端在 background.js 中使用 switch-case 语句分发处理：

// extension/background.js (伪代码示例)
switch (action) {
  case 'click': {
    const tab = await getSessionTab(port);
    // 实现点击逻辑
    return { ok: true };
  }
  case 'fill': {
    // 实现填充逻辑
    return { ok: true };
  }
  // ... 其他处理程序
}

资料来源：CONTRIBUTING.md:60-80

相关页面

• 快速开始指南 — 安装与配置
• 导航与内容工具 — 页面导航和内容提取
• 提供商集成 — Stripe、HubSpot 等 API Token 提取
• HTTP 请求工具 — CORS 绕过请求
• 贡献指南 — 如何添加新工具

工具概览

Browser MCP 的数据与网络工具可分为三大类别：

资料来源：mcp-server/tools.js:1-50

架构设计

通信流程

数据与网络工具的完整调用链路如下：

graph TD
    A[Claude Code] -->|browser_get_page_content| B[MCP Server]
    B -->|WebSocket| C[Extension Offscreen]
    C -->|Chrome Debugger API| D[目标网页]
    D -->|响应数据| C
    C -->|JSON结果| B
    B -->|stdio| A
    
    E[browser_fetch] -->|绕过CORS| F[Extension Background]
    F -->|fetch| G[外部API]
    G -->|响应| F
    F -->|数据| E

MCP 服务器通过标准输入输出（stdio）与 Claude Code 通信，同时作为 WebSocket 客户端连接到 Chrome 扩展。扩展后台脚本负责执行实际的浏览器操作，并通过 Chrome Debugger API 或 fetch API 与目标页面或外部服务交互。资料来源：mcp-server/index.js:1-30

WebSocket 连接机制

MCP 服务器在端口 9876-9885 范围内绑定第一个可用端口，扩展的离屏文档每 2 秒扫描一次这些端口以建立连接。资料来源：extension/offscreen.js

内容获取工具

browser_get_page_content

获取当前页面的内容，可以返回纯文本或完整 HTML。

返回值示例（text 格式）：

首页 / 登录 / 产品
欢迎使用 Browser MCP

这是一个演示页面，用于展示浏览器自动化功能。

返回值示例（html 格式）：

<!DOCTYPE html>
<html>
<head><title>Browser MCP Demo</title></head>
<body>
  <h1>欢迎使用 Browser MCP</h1>
  <p>这是一个演示页面</p>
</body>
</html>

此工具适用于需要解析页面结构或提取特定文本内容的场景，如数据采集、内容分析等。资料来源：mcp-server/tools.js:14-28

browser_screenshot

拍摄当前标签页可见区域的截图。

使用说明：

• 返回 base64 编码的 PNG 图像
• 如果提供 path 参数，图片将直接保存到指定路径
• 使用 Chrome Debugger API 实现，即使标签页不在焦点也能正常工作

返回值：

{
  "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAA...",
  "path": "/tmp/screenshot.png"
}

⚠️ 社区反馈：有用户建议截图工具应直接接收文件路径并保存文件，而非传递 base64 数据。当前版本（v1.16.1）已支持 path 参数直接保存到磁盘。资料来源：mcp-server/tools.js:30-44

browser_execute_script

在当前页面上下文中执行 JavaScript 代码，并返回执行结果。

示例调用：

// 提取页面中所有链接
browser_execute_script({
  code: "Array.from(document.querySelectorAll('a')).map(a => ({href: a.href, text: a.textContent}))"
})

返回值示例：

[
  {"href": "https://example.com/about", "text": "关于我们"},
  {"href": "https://example.com/contact", "text": "联系我们"}
]

此工具提供了最大的灵活性，允许用户执行任意 JavaScript 来提取或操作页面内容。资料来源：mcp-server/tools.js:46-62

网络交互工具

browser_wait_for_network

等待网络请求完成（网络空闲）。

使用场景：

• 单页应用（SPA）加载完成后获取内容
• 等待 AJAX 请求完成
• 确保动态加载的内容已渲染

返回值：

{
  "ok": true,
  "message": "Network idle after 1.2s"
}

此工具通过 Chrome Debugger Protocol 监控网络活动，实现比传统 setTimeout 更精确的等待机制。资料来源：mcp-server/tools.js:64-78

browser_fetch

从扩展后台上下文发起 HTTP 请求，绕过同源策略（CORS）限制。

返回值：

{
  "ok": true,
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"data\": \"example\"}"
}

使用优势：

• 绕过浏览器同源策略限制
• 可访问需要特定来源头的 API
• 支持在已登录会话中发起请求

示例：调用外部 API 获取数据

browser_fetch({
  url: "https://api.example.com/data",
  method: "GET",
  headers: {
    "Authorization": "Bearer token123"
  }
})

此工具对于需要调用第三方 API 或跨域获取数据的自动化任务至关重要。相比 Playwright MCP 等竞品，Browser MCP 的 CORS 绕过能力是其显著优势。资料来源：mcp-server/tools.js:80-110

browser_handle_dialog

处理页面弹出的 JavaScript 对话框（alert、confirm、prompt）。

返回值：

{
  "ok": true,
  "dialogType": "confirm",
  "action": "accept"
}

使用示例：

// 接受确认对话框
browser_handle_dialog({ action: "accept" })

// 向 prompt 对话框输入文本
browser_handle_dialog({ action: "accept", prompt_text: "用户名" })

此工具用于处理网页中可能出现的各种弹窗，确保自动化流程不会因对话框而中断。资料来源：mcp-server/tools.js:112-128

数据提取工具

browser_extract_token

从常用第三方服务的网页界面中提取 API Token。

支持的提供商：

使用流程：

1. 调用工具导航到目标服务的 Token 页面
2. 浏览器 MCP 会导航到对应页面并提供提取说明
3. 用户手动复制 Token 或使用页面交互工具提取

// 提取 Stripe API Key
browser_extract_token({ provider: "stripe" })

返回值：

{
  "ok": true,
  "provider": "stripe",
  "url": "https://dashboard.stripe.com/apikeys",
  "instructions": "Look for the Secret key starting with sk_live_ or sk_test_"
}

资料来源：mcp-server/tools.js:220-280

browser_collect

收集用户交互数据，用于 Bug 报告和功能反馈。

使用场景：

当用户描述了缺失的功能、遇到的问题或展示有趣的使用案例时，可以调用此工具生成 GitHub Issue 链接。

browser_about({
  intent: "wish",
  title: "支持 hCaptcha v3 识别",
  body: "希望在浏览器自动化中能自动处理 hCaptcha"
})

返回值：

{
  "ok": true,
  "submit_url": "https://github.com/Agent360dk/browser-mcp/issues/new?template=wish.yml&title=..."
}

此工具是用户向项目反馈的重要渠道，也是 Browser MCP 社区驱动发展的核心机制。资料来源：mcp-server/tools.js:280-320

使用模式与最佳实践

常见工作流程

#### 1. 页面内容抓取

graph LR
    A[navigate 到目标页面] --> B[wait_for_network 等待加载]
    B --> C[get_page_content 获取内容]
    C --> D[execute_script 提取数据]
    D --> E[screenshot 截图留证]

完整示例：

// 1. 导航到目标页面
browser_navigate({ url: "https://news.example.com/tech" })

// 2. 等待动态内容加载
browser_wait_for_network({ timeout: 10000 })

// 3. 提取文章标题和链接
const articles = browser_execute_script({
  code: `
    Array.from(document.querySelectorAll('article h2 a')).map(a => ({
      title: a.textContent.trim(),
      url: a.href
    }))
  `
})

// 4. 截图留证
browser_screenshot({ path: "/tmp/news-screenshot.png" })

#### 2. API 数据获取（绕过 CORS）

graph LR
    A[已登录的浏览器会话] --> B[browser_fetch 调用API]
    B --> C[扩展后台处理请求]
    C --> D[返回JSON数据]

完整示例：

// 导航到已登录的内部系统
browser_navigate({ url: "https://internal.company.com" })

// 使用 browser_fetch 获取需要认证的 API 数据
const data = browser_fetch({
  url: "https://internal.company.com/api/users",
  method: "GET"
})

性能注意事项

远程使用与网络配置

⚠️ 社区关注点：有用户报告尝试远程使用 Browser MCP（Linux 服务器 + systemd 方案），但 Web 扩展无法检测远程 MCP 服务器，这可能是出于安全考虑的设计。

Browser MCP 当前主要设计用于本地环境：

• MCP 服务器与扩展通过本地 WebSocket 连接
• 端口扫描范围限制在 9876-9885

对于远程使用场景，需要额外的网络配置方案，如 VPN 或端口转发。

资料来源：社区 Issue #1：远程使用讨论

常见问题排查

截图返回空或失败

可能原因：

1. 扩展未正确加载
2. Chrome Debugger API 不可用

解决方案：

• 检查扩展是否在 chrome://extensions 中启用
• 点击扩展图标 → "Reconnect"
• 等待 2-3 秒让端口扫描完成

browser_fetch 请求失败

可能原因：

1. 目标 URL 不支持跨域
2. 请求头配置错误
3. 网络连接问题

解决方案：

• 确认目标 URL 可访问
• 检查 headers 配置是否正确
• 使用 browser_navigate 先访问目标域名的页面

内容获取不完整

可能原因：

• 页面使用懒加载，内容未完全渲染
• 需要滚动页面才能加载更多内容

解决方案：

// 滚动到底部触发懒加载
browser_scroll({ behavior: "smooth", y: 3000 })

// 等待新内容加载
browser_wait_for_network({ timeout: 5000 })

// 再次获取内容
browser_get_page_content({ format: "text" })

资料来源：mcp-server/tools.js:30-44

相关工具链接

• 交互工具：browser_click、browser_fill、browser_hover
• 导航工具：browser_navigate、browser_wait
• 窗口管理：browser_new_window、browser_close_window
• 配置与管理：browser_about、browser_settings

参考资料

概述

Browser MCP 采用人工介入（Human-in-the-Loop）策略处理 CAPTCHA 挑战。当自动化流程遇到 CAPTCHA 时，系统会暂停执行并请求人工用户在浏览器中手动完成验证。这种设计既保证了自动化的连续性，又确保了在需要人类判断的场景（如人机验证）下能够顺利通过。

Browser MCP 的核心竞争力之一就是能够处理真实浏览器中的 2FA（双因素认证）、CAPTCHA 和凭证输入问题，这也是该工具区别于传统无头浏览器自动化方案的关键优势。资料来源：README.md:1-20

工作原理

架构流程

graph TD
    A[Claude Code 自动化流程] --> B{遇到 CAPTCHA?}
    B -->|是| C[调用 browser_ask_user]
    C --> D[Extension 弹出用户交互窗口]
    D --> E[用户在浏览器中手动完成验证]
    E --> F[Extension 通知 MCP Server 继续]
    F --> G[自动化流程恢复执行]
    B -->|否| H[继续正常自动化流程]
    
    style D fill:#f9f,color:#000
    style E fill:#9f9,color:#000

组件协作

资料来源：extension/background.js 和 mcp-server/index.js:1-30

远程使用场景

根据社区反馈，当 Browser MCP 在远程 Linux 服务器上通过 systemd 运行时，Web Extension 可能无法检测到远程 MCP 服务器。这是出于安全考虑的设计决策。对于此类场景，用户需要配置额外的端口映射或本地 MCP 网关方案。资料来源：社区 Issue #1

使用方法

基本调用流程

当 Claude Code 在执行自动化任务过程中检测到 CAPTCHA 时，会自动调用 browser_ask_user 工具：

// Claude Code 内部调用示例
const result = await mcpServer.callTool({
  name: "browser_ask_user",
  arguments: {
    action: "Solve the CAPTCHA shown in the browser",
    context: "2FA verification required at login step"
  }
});

典型使用场景

工具参考

browser_ask_user

核心工具，用于在自动化流程中请求人工介入处理 CAPTCHA、2FA 或凭证输入。

返回值：

{
  "success": true,
  "message": "用户已完成验证，自动化流程将继续"
}

资料来源：mcp-server/tools.js:1-50

browser_about

当用户遇到无法解决的 CAPTCHA 或发现相关问题时，可通过此工具提交反馈。

资料来源：mcp-server/tools.js:100-150

最佳实践

1. 提前识别 CAPTCHA 场景

在编写自动化脚本时，尽量预判可能触发 CAPTCHA 的操作：

// 导航到可能需要验证的页面
await browser_navigate("https://example.com/login");

// 页面加载后检查是否出现 CAPTCHA
const content = await browser_get_page_content();

// 如果检测到验证码特征，调用人工介入
if (content.includes("captcha") || content.includes("验证")) {
  await browser_ask_user({
    action: "Complete the CAPTCHA verification",
    context: "Login page requires human verification"
  });
}

2. 提供清晰的操作指引

在调用 browser_ask_user 时，提供足够的信息帮助用户快速完成验证：

await browser_ask_user({
  action: "Click all images containing storefronts",
  context: "reCAPTCHA challenge on contact form submission"
});

3. 处理验证超时

设置合理的等待时间，避免用户因操作延迟而导致流程中断：

已知限制

安全限制

• Web Extension 不会检测远程 MCP 服务器，这是出于安全考虑的设计决策。资料来源：社区 Issue #1
• 所有人工介入操作都必须在本地 Chrome 浏览器中完成

技术限制

• 不支持自动识别和解决所有类型的 CAPTCHA
• 某些高级 CAPTCHA（如 hCaptcha Enterprise、reCAPTCHA v3）可能需要额外配置

相关工具

参见

• 安装指南 — 完整的 Browser MCP 安装流程
• 工具列表 — 所有 34 个浏览器自动化工具
• 使用案例 — 用户分享的真实自动化场景
• 功能愿望单 — 社区请求的功能特性

概述

Browser MCP 的人机交互机制主要通过以下工具实现：

资料来源：mcp-server/tools.js:1-50

该机制的设计理念是：AI 处理常规自动化任务，但在遇到需要人类判断或安全敏感的步骤时，自动移交控制权给用户。这既保证了自动化效率，又确保了安全性。

核心工具详解

browser_ask_user

browser_ask_user 是人机交互的主要入口点。当 AI 需要用户的直接参与时，会调用此工具并显示交互界面。

{
  name: 'browser_ask_user',
  description: 'Ask the user for input or confirmation before proceeding. Use when you need human input to continue — e.g. filling in credentials, solving a CAPTCHA, approving an action, or clarifying ambiguous instructions.',
  inputSchema: {
    type: 'object',
    properties: {
      message: { 
        type: 'string', 
        description: 'The question or request to show the user' 
      },
      options: { 
        type: 'array', 
        items: { type: 'string' },
        description: 'Button labels for options (default: ["Yes", "No"])' 
      },
      default_response: { 
        type: 'string', 
        description: 'Auto-submit after timeout in ms (default: 300000 = 5 min)' 
      },
    },
    required: ['message'],
  },
}

资料来源：mcp-server/tools.js:104-125

#### 使用流程

sequenceDiagram
    participant AI as Claude Code (AI代理)
    participant MCP as MCP Server
    participant EXT as Chrome Extension
    participant USER as 用户
    participant CHROME as Chrome Browser

    AI->>MCP: browser_ask_user(message, options)
    MCP->>EXT: 转发请求
    EXT->>USER: 在扩展弹窗中显示交互界面
    USER->>EXT: 输入响应/选择选项
    EXT-->>MCP: 返回用户输入
    MCP-->>AI: 返回结果
    AI->>AI: 根据响应继续执行下一步

#### 典型使用场景

1. 双因素认证（2FA）：当网站要求输入短信或邮件验证码时，AI 无法自动获取，此时请求用户输入
2. CAPTCHA 解决：对于 AI 无法自动识别的验证码，请求用户手动完成
3. 敏感操作确认：删除数据、发送邮件等不可逆操作前请求用户确认
4. 凭证输入：在安全意识较高的网站上输入密码或 API 密钥

browser_extract_token

browser_extract_token 是专门用于第三方服务 API Token 提取的工具，简化了 OAuth 或 API Key 授权流程。

{
  name: 'browser_extract_token',
  description: 'Navigate to a provider page and help the user copy their API token, returning it for use in browser_fetch calls. Supports Stripe, HubSpot, Slack, Shopify, Linear, Notion, Intercom, and GitHub.',
  inputSchema: {
    type: 'object',
    properties: {
      provider: { 
        type: 'string', 
        enum: ['stripe', 'hubspot', 'slack', 'shopify', 'linear', 'notion', 'intercom', 'github'],
        description: 'The API provider to extract token from' 
      },
    },
    required: ['provider'],
  },
}

资料来源：mcp-server/tools.js:126-145

#### 支持的提供商

资料来源：mcp-server/tools.js:191-220

browser_handle_dialog

处理浏览器的原生对话框（alert、confirm、prompt），确保自动化流程不会被弹窗阻塞。

{
  name: 'browser_select_option',
  description: 'Select an option in a dropdown/select element. Works on native <select> elements and custom dropdowns including Angular Material, React Select, and custom autocomplete components.',
  inputSchema: {
    type: 'object',
    properties: {
      selector: { type: 'string', description: 'CSS selector for the dropdown' },
      option: { type: 'string', description: 'Value or text of option to select' },
    },
  },
}

资料来源：mcp-server/tools.js:85-103

扩展弹窗界面

Browser MCP 的用户交互界面通过 Chrome 扩展弹窗实现，提供实时状态展示和操作入口。

界面组件

扩展弹窗（popup.html）包含以下核心区域：

<div class="session-header">
  <span class="session-label">Session</span>
  <span class="session-color" id="sessionColor"></span>
</div>
<div class="tab-list" id="tabList"></div>
<div class="action-log" id="actionLog"></div>
<div class="controls">
  <button id="reconnectBtn">Reconnect</button>
  <button id="newSessionBtn">New Session</button>
</div>

资料来源：extension/popup.html 和 extension/popup.js

状态展示

弹窗实时显示以下信息：

交互控制

用户可以通过弹窗界面执行以下操作：

1. Reconnect：重新连接 MCP 服务器（用于连接断开时）
2. New Session：创建新的浏览器会话（支持多会话隔离）
3. Tab 切换：在会话内的多个标签页之间快速切换
4. 日志查看：查看 AI 执行的操作历史，便于调试

多会话管理

Browser MCP 支持最多 10 个并发 AI 会话，每个会话使用独立的浏览器标签页组，通过颜色编码进行区分。

graph TB
    subgraph Browser["Chrome 浏览器"]
        subgraph Session1["Session 1 (蓝色)"]
            T1_1["Tab 1"]
            T1_2["Tab 2"]
        end
        subgraph Session2["Session 2 (绿色)"]
            T2_1["Tab 3"]
            T2_2["Tab 4"]
        end
        subgraph SessionN["Session N (红色)"]
            TN_1["Tab N-1"]
            TN_2["Tab N"]
        end
    end
    
    AI1["Claude Code (AI 1)"] --> Session1
    AI2["Claude Code (AI 2)"] --> Session2
    AIN["Claude Code (AI N)"] --> SessionN

会话隔离机制

每个会话的浏览器状态完全隔离，包括：

• Cookie 和会话存储
• LocalStorage 和 SessionStorage
• 缓存数据
• 登录状态

这使得同一个 AI 代理可以同时管理多个网站的不同账户，或多个 AI 实例可以并行处理不同的自动化任务而互不干扰。

通信架构

人机交互机制的实现依赖于一套精心设计的通信架构，确保 AI 代理、Chrome 扩展和用户界面之间的高效协作。

flowchart LR
    subgraph Claude["Claude Code"]
        A[用户请求]
    end
    
    subgraph MCP["MCP Server"]
        B[工具调用]
        C{交互类型}
        D[browser_ask_user]
        E[browser_extract_token]
        F[browser_handle_dialog]
    end
    
    subgraph WS["WebSocket 连接"]
        G[消息传递]
    end
    
    subgraph Extension["Chrome Extension"]
        H[background.js]
        I[offscreen.js]
        J[popup.js]
    end
    
    subgraph User["用户界面"]
        K[弹窗交互]
        L[Token 输入]
    end
    
    A --> B
    B --> C
    C --> D
    C --> E
    C --> F
    D --> G
    E --> G
    F --> G
    G --> H
    H --> I
    I --> J
    J --> K
    K --> L

端口扫描与连接

由于 Chrome 扩展的安全限制，offscreen document 需要主动扫描可用端口来建立 WebSocket 连接：

// 扫描端口范围 9876-9885
const START_PORT = 9876;
const END_PORT = 9885;

async function findAvailablePort() {
  for (let port = START_PORT; port <= END_PORT; port++) {
    try {
      const response = await fetch(`http://localhost:${port}/status`);
      if (response.ok) {
        return port;
      }
    } catch (e) {
      continue;
    }
  }
  return null;
}

资料来源：extension/offscreen.js 和 mcp-server/index.js

请求-响应流程

当 AI 调用 browser_ask_user 时的完整流程：

1. 请求发起：Claude Code 通过 MCP 协议发送 browser_ask_user 调用
2. MCP 转发：MCP Server 将请求转换为内部指令，通过 WebSocket 发送给扩展
3. 界面更新：扩展的 background.js 接收指令，更新 popup 状态并显示交互界面
4. 用户输入：用户在弹窗中输入响应
5. 结果返回：响应通过 WebSocket 传回 MCP Server
6. AI 恢复：Claude Code 接收结果，继续执行后续步骤

远程使用场景

社区用户 reported 了远程使用 MCP 服务器的需求场景：当 MCP 网关运行在局域网服务器上，而浏览器运行在本地机器上时，需要一种方式让扩展能够连接到远程服务器。

graph LR
    subgraph Local["本地机器"]
        BROWSER["Chrome 浏览器"]
        EXT["Browser MCP 扩展"]
    end
    
    subgraph Remote["局域网服务器"]
        MCP_SERVER["MCP Server"]
        GATEWAY["MCP Gateway"]
    end
    
    EXT -->|"WebSocket"| GATEWAY
    MCP_SERVER -->|"stdio"| GATEWAY

注意：由于安全考虑，扩展默认不会自动检测远程 MCP 服务器。社区已探索使用 systemd 服务在 Linux 上运行远程 MCP 服务器的解决方案。

资料来源：社区 Issue #1 - "Using browser-mcp remotely (linux + systemd solution)"

配置与参数

工具默认参数

环境变量

常见问题

交互超时

如果用户未在指定时间内响应（默认 5 分钟），browser_ask_user 会返回默认响应或超时错误。建议在关键操作前向用户说明需要他们进行什么操作。

远程连接失败

扩展无法检测远程 MCP 服务器是设计决策，出于安全考虑。如需远程使用，请确保在本地机器上运行 MCP Server，或使用 VPN 将远程服务器暴露到本地网络。

多会话冲突

当多个 AI 实例尝试操作同一会话的标签页时，可能发生冲突。建议为每个 AI 实例分配独立的会话，或使用标签页锁定机制避免并发操作。

最佳实践

1. 明确用户指令：在调用 browser_ask_user 时，提供清晰的操作说明和预期结果
2. 合理超时设置：根据操作复杂度调整超时时间，避免过早超时
3. 会话隔离：对于敏感操作，使用专用会话避免信息泄露
4. 状态检查：在执行关键操作前，先通过 popup 确认当前会话状态
5. 错误处理：准备好交互失败时的降级方案

参见

• 快速开始指南 - 安装与基础配置
• 工具列表 - 完整工具参考
• 贡献指南 - 报告问题与功能请求
• 使用案例 - 社区实践分享
• 愿望清单 - 功能请求跟踪

概述

Browser MCP 提供了内置的第三方服务集成功能，允许 Claude Code 通过真实 Chrome 浏览器自动从各大平台提取 API 密钥和访问令牌。这一功能解决了 AI 代理在自动化工作流中需要手动获取凭证的痛点，实现了从浏览器到自动化流程的无缝衔接。

截至 v1.16.1 版本，Browser MCP 内置了 9 个提供商集成，包括 Stripe、HubSpot、Slack、Shopify 等主流平台。每个提供商都配置了专用的令牌页面 URL 和提取指令，引导用户快速定位并获取所需的凭证。

资料来源：README.md

核心工具：browser_extract_token

功能说明

browser_extract_token 是 Browser MCP 中用于提取第三方服务 API 令牌的核心工具。它通过以下方式工作：

1. 导航到指定提供商的令牌页面
2. 通过浏览器自动化操作获取页面内容
3. 使用正则表达式从页面 HTML 中提取目标令牌
4. 返回提取结果给 Claude Code

该工具特别适用于需要 API 访问权限但尚未配置凭证的自动化场景。例如，当用户需要让 AI 自动完成 Stripe 支付退款操作时，可以先调用此工具获取 Stripe 的 API 密钥。

资料来源：mcp-server/tools.js:181-217

输入参数

返回值

支持的提供商

提供商列表

Browser MCP 当前支持以下第三方服务的令牌提取：

Stripe 集成

Stripe 是最常用的支付集成场景。Browser MCP 配置了专用的密钥页面 URL，并附带提取指令引导用户找到正确格式的密钥。

提取目标：

• 生产密钥：sk_live_ 前缀
• 测试密钥：sk_test_ 前缀

使用示例：

// 获取 Stripe API 密钥
browser_navigate({ url: 'https://dashboard.stripe.com/apikeys' });
browser_extract_token({ provider: 'stripe' });

资料来源：mcp-server/tools.js:219-227

HubSpot 集成

HubSpot CRM 集成支持获取私有应用的访问令牌。这对于自动化销售流程、联系人管理和营销自动化非常有用。

提取目标： Private App Access Token

提取路径：

1. 导航至 app.hubspot.com/settings/
2. 进入 Integrations → Private Apps
3. 创建或选择现有应用
4. 复制 Access Token

Slack 集成

Slack 集成用于获取 Bot User OAuth Token，这使得 AI 能够代表用户执行消息发送、频道管理等操作。

提取目标： Bot User OAuth Token (xoxb-...)

提取路径：

1. 导航至 api.slack.com/apps
2. 选择目标应用
3. 进入 OAuth & Permissions
4. 复制 Bot User OAuth Token

Shopify 集成

Shopify 集成支持从 Shopify 管理后台提取 Admin API 访问令牌，适用于电商自动化场景如订单管理、库存同步等。

提取目标： Admin API Access Token

工作原理

架构流程

graph TD
    A[Claude Code] -->|browser_extract_token| B[MCP Server]
    B -->|tool call| C[Chrome Extension]
    C -->|CDP| D[Chrome Browser]
    D -->|navigate| E[Provider Console]
    E -->|page content| D
    D -->|HTML| C
    C -->|parse| F[Token Extraction]
    F -->|regex match| G[API Token]
    G -->|response| B
    B -->|tool result| A

令牌提取机制

Browser MCP 使用正则表达式模式从页面 HTML 中匹配目标令牌。不同提供商使用不同的正则模式以适应各自的令牌格式：

• Stripe： 匹配 sk_(live|test)_[a-zA-Z0-9]+
• Slack： 匹配 xoxb-[a-zA-Z0-9-]+
• HubSpot： 通用令牌格式匹配

资料来源：mcp-server/tools.js:219-240

Provider 配置结构

每个提供商在 PROVIDER_PAGES 对象中定义以下属性：

export const PROVIDER_PAGES = {
  stripe: {
    url: 'https://dashboard.stripe.com/apikeys',
    instructions: 'Look for the Secret key starting with sk_live_ or sk_test_',
  },
  hubspot: {
    url: 'https://app.hubspot.com/settings/',
    instructions: 'Navigate to Integrations → Private Apps → ...',
  },
  // ... 更多提供商
};

集成优势

相比其他方案的优点

资料来源：README.md

典型使用场景

场景一：Stripe 退款自动化

// 1. 获取 Stripe API 密钥
browser_extract_token({ provider: 'stripe' });

// 2. 使用密钥进行 API 调用
browser_execute_script({
  script: `
    fetch('https://api.stripe.com/v1/refunds', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer sk_live_xxx',
        'Content-Type': 'application/x-www-form-urlencoded'
      },
      body: 'charge=ch_xxx'
    })
  `
});

场景二：Slack 通知发送

// 1. 获取 Slack Bot Token
browser_extract_token({ provider: 'slack' });

// 2. 发送通知
browser_execute_script({
  script: `
    fetch('https://slack.com/api/chat.postMessage', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer xoxb-xxx',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        channel: '#alerts',
        text: 'Process completed successfully'
      })
    })
  `
});

扩展第三方集成

添加新提供商

如需添加新的第三方服务集成，可按照以下步骤修改源码：

步骤 1：在 tools.js 中定义 Provider 配置

在 PROVIDER_PAGES 对象中添加新的提供商条目：

export const PROVIDER_PAGES = {
  // ... 现有配置
  myprovider: {
    url: 'https://api.myprovider.com/tokens',
    instructions: 'Navigate to Settings → API Keys → copy your key',
  },
};

步骤 2：添加 Tool 定义

在 TOOLS 数组中添加或扩展 browser_extract_token 工具的 provider 选项枚举：

{
  name: 'browser_extract_token',
  description: '...',
  inputSchema: {
    type: 'object',
    properties: {
      provider: {
        type: 'string',
        enum: ['stripe', 'hubspot', 'slack', 'shopify', 'myprovider'],
        description: 'Service provider identifier',
      },
    },
    required: ['provider'],
  },
}

步骤 3：在 background.js 中实现提取逻辑

在扩展后台服务中添加新的 case 处理分支：

case 'extract_token': {
  const { provider, client_id, client_secret } = args;
  const config = PROVIDER_PAGES[provider];
  
  // 导航到提供商页面
  await navigate(tabId, config.url);
  
  // 提取令牌逻辑
  const pageContent = await getPageContent(tabId);
  const token = extractToken(pageContent, provider);
  
  return { token, provider, url: config.url };
}

资料来源：extension/background.js

限制与注意事项

安全考虑

1. 令牌存储： 提取的令牌以纯文本形式返回，建议通过环境变量或密钥管理服务存储
2. 网络传输： 令牌通过 MCP 协议传输，确保 Claude Code 运行在可信环境
3. 远程使用： Web 扩展不会检测远程 MCP 服务器，这是出于安全考虑的设计选择

⚠️ 社区反馈：用户报告 Web 扩展不会检测远程 MCP 服务器，这可能影响跨网络自动化场景。如需远程使用，请参考社区提供的 systemd 解决方案。

资料来源：社区 Issue #1

技术限制

版本兼容性

browser_extract_token 工具定义在 mcp-server/tools.js 中，随 MCP 服务器版本更新。新增提供商可能需要同时更新扩展端实现。

相关资源

• 工具列表 — 所有 34 个浏览器自动化工具完整参考
• 安装指南 — 完整的 Browser MCP 安装配置教程
• 架构说明 — MCP 服务器与扩展的通信机制详解

Pitfall Log / 踩坑日志

项目：agent360dk/browser-mcp

摘要：发现 9 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Using browser-mcp remotely (linux + systemd solution)。

1. 安装坑 · 来源证据：Using browser-mcp remotely (linux + systemd solution)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Using browser-mcp remotely (linux + systemd solution)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_5c66b5c80c434888a9fd4ad95af8793f | https://github.com/Agent360dk/browser-mcp/issues/1 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

2. 安装坑 · 失败模式：installation: Using browser-mcp remotely (linux + systemd solution)

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Using browser-mcp remotely (linux + systemd solution)
• 对用户的影响：Developers may fail before the first successful local run: Using browser-mcp remotely (linux + systemd solution)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Using browser-mcp remotely (linux + systemd solution). Context: Observed when using linux
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_9bfdeebbaac14508096abe351728049c | https://github.com/Agent360dk/browser-mcp/issues/1 | Using browser-mcp remotely (linux + systemd solution)

3. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | mcp_registry:io.github.Agent360dk/browser-mcp:1.16.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Agent360dk%2Fbrowser-mcp/versions/1.16.1 | host_targets=mcp_host, claude, claude_code

4. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:io.github.Agent360dk/browser-mcp:1.16.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Agent360dk%2Fbrowser-mcp/versions/1.16.1 | README/documentation is current enough for a first validation pass.

5. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Agent360dk/browser-mcp:1.16.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Agent360dk%2Fbrowser-mcp/versions/1.16.1 | last_activity_observed missing

6. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:io.github.Agent360dk/browser-mcp:1.16.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Agent360dk%2Fbrowser-mcp/versions/1.16.1 | no_demo; severity=medium

7. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:io.github.Agent360dk/browser-mcp:1.16.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Agent360dk%2Fbrowser-mcp/versions/1.16.1 | no_demo; severity=medium

8. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Agent360dk/browser-mcp:1.16.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Agent360dk%2Fbrowser-mcp/versions/1.16.1 | issue_or_pr_quality=unknown

9. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Agent360dk/browser-mcp:1.16.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Agent360dk%2Fbrowser-mcp/versions/1.16.1 | release_recency=unknown