# https://github.com/Agent360dk/browser-mcp 项目说明书生成时间：2026-05-26 16:04:23 UTC ## 目录 - [Browser MCP 概述](#page-overview) - [安装配置指南](#page-installation) - [系统架构](#page-architecture) - [多会话管理](#page-multi-session) - [导航与内容工具](#page-tools-navigation) - [交互操作工具](#page-tools-interaction) - [数据与网络工具](#page-tools-data) - [CAPTCHA 解决](#page-captcha-solving) - [人机交互机制](#page-human-in-loop) - [第三方服务集成](#page-provider-integrations) ## Browser MCP 概述 ### 相关页面相关主题：[安装配置指南](#page-installation), [系统架构](#page-architecture)

相关源码文件

以下源码文件用于生成本页说明： - [README.md](https://github.com/Agent360dk/browser-mcp/blob/main/README.md) - [mcp-server/index.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/index.js) - [mcp-server/tools.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js) - [mcp-server/package.json](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/package.json) - [CONTRIBUTING.md](https://github.com/Agent360dk/browser-mcp/blob/main/CONTRIBUTING.md) - [USE_CASES.md](https://github.com/Agent360dk/browser-mcp/blob/main/USE_CASES.md) - [extension/manifest.json](https://github.com/Agent360dk/browser-mcp/blob/main/extension/manifest.json)

# Browser MCP 概述 Browser MCP 是由 Agent360 开发的开源项目，它通过 Chrome 扩展程序与 MCP（Model Context Protocol）服务器的协作，使 Claude Code 能够控制用户真实的 Chrome 浏览器。该项目支持多会话并发（最多 10 个并发 AI 会话）、人工介入机制（2FA 验证码、凭证输入）以及内置的第三方服务集成（如 Stripe、HubSpot、Slack 等），总计提供 34 个浏览器自动化工具。资料来源：[README.md:1-10]() ## 核心特性 Browser MCP 与其他浏览器自动化方案相比，具有以下独特优势： | 特性 | Browser MCP | Playwright MCP | BrowserMCP.io | |------|-------------|----------------|---------------| | 浏览器类型 | 真实 Chrome | 无头浏览器（新会话） | 真实 Chrome | | 登录状态 | 复用已有认证 | 每次需重新登录 | 复用已有认证 | | 多会话支持 | 10 个并发会话，带颜色标识的标签页组 | 单会话 | 单会话 | | 人工介入 | `browser_ask_user` 支持 2FA、CAPTCHA、凭证输入 | 不支持 | 不支持 | | 第三方集成 | 9 个内置集成（Stripe、HubSpot、Slack 等） | 无 | 无 | | CORS 绕过 | `browser_fetch` 从扩展后台发起 | 不适用 | 有限支持 | | 网络监控 | `browser_wait_for_network` 通过 CDP | 内置支持 | 无 | | CSP 严格站点 | 全面使用 Chrome Debugger API | 支持（无头） | 有限支持 | | 自定义下拉框 | 支持 Angular Material、React Select | 支持（无头） | 有限支持 | 资料来源：[README.md:76-92]() ## 系统架构 ### 整体架构 Browser MCP 由两个核心组件构成：Chrome 扩展程序（负责与浏览器 API 交互）和 MCP 服务器（负责与 Claude Code 通过标准输入/输出通信）。 ```mermaid 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 小时后自动退出 ```mermaid 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 个工具，涵盖导航、内容获取、交互操作、状态等待、标签页管理等多个类别。 ### 导航与内容获取 | 工具名称 | 描述 | 关键参数 | |---------|------|---------| | `browser_navigate` | 导航到指定 URL，默认复用当前标签页 | `url`（必需）、`new_tab`（可选，是否在新标签页打开） | | `browser_get_page_content` | 获取当前页面的文本或 HTML 内容 | `format`（text/html） | | `browser_screenshot` | 截取当前标签页可见区域的截图 | `path`（可选，保存路径） | | `browser_execute_script` | 在页面上下文中执行 JavaScript 代码 | `code`（必需） | 资料来源：[mcp-server/tools.js:1-50]() ### 交互操作 | 工具名称 | 描述 | 选择器支持 | |---------|------|-----------| | `browser_click` | 点击元素，支持 CSS 或文本选择器 | `text=Submit`、`button:text(Next)` | | `browser_fill` | 填充输入字段（适用于 CSP 严格站点） | CSS 选择器 | | `browser_press_key` | 发送键盘事件 | Enter、Tab、Escape、修饰键 | | `browser_scroll` | 滚动到元素或指定像素位置 | CSS 选择器或像素值 | | `browser_hover` | 悬停以触发工具提示或下拉菜单 | CSS 选择器 | | `browser_select_option` | 选择选项，支持原生 ``、`

` 和 `contenteditable` 元素
- 在 CSP 严格站点也能正常工作（通过 Chrome Debugger API 实现）
- 可选择性地在填充后按下 Enter 键

资料来源：[mcp-server/tools.js:110-140]()

### browser_press_key 键盘按键

模拟键盘按键操作。

```javascript
{
  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 滚动

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

```javascript
{
  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 等待

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

```javascript
{
  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'],
  },
}
```

**等待状态说明**：

| 状态 | 说明 |
|------|------|
| `attached` | 元素已添加到 DOM |
| `detached` | 元素从 DOM 中移除 |
| `visible` | 元素可见且可交互 |
| `hidden` | 元素不可见或隐藏 |

### browser_hover 悬停

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

```javascript
{
  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>` 元素或自定义下拉菜单的选项。

```javascript
{
  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 自动完成组合框

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

```javascript
{
  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）。

```javascript
{
  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 和凭据输入。

```javascript
{
  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]()

## 使用模式与最佳实践

### 基础交互模式

典型的页面交互流程：

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

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

// 3. 填充登录信息
browser_fill({ selector: "#username", value: "user@example.com" })
browser_fill({ selector: "#password", value: "secretpassword" })

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

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

### 处理复杂下拉菜单

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

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

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

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

### 处理需要用户参与的流程

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

资料来源：[README.md:60-85]()

## 故障排除

### 点击未生效

| 问题 | 解决方案 |
|------|----------|
| 元素不可见 | 先调用 `browser_scroll` 滚动到元素可见区域 |
| 元素被遮挡 | 使用 `browser_click` 的 `modifier` 参数配合 Control 点击 |
| SPA 点击无响应 | 尝试文本选择器：`browser_click({ selector: "text=提交" })` |
| 动态内容 | 增加 `browser_wait` 等待元素加载完成 |

### 输入未写入

| 问题 | 解决方案 |
|------|----------|
| CSP 限制站点 | 使用 `browser_fill`，它通过 Debugger API 绕过 CSP |
| 输入框被重置 | 检查是否有 React/Vue 的 onChange 事件，尝试输入后点击其他地方触发变更 |
| 只读输入框 | 先移除只读属性：`browser_execute_script({ script: "..." })` |

### 滚动问题

| 问题 | 解决方案 |
|------|----------|
| 滚动后元素仍不可见 | 设置 `into_view: false`，然后手动计算滚动距离 |
| 无限滚动页面 | 使用 `browser_wait` 配合 `state: "attached"` 检测新内容加载 |

### 常见错误处理

```javascript
// 使用 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 使用方法映射表将工具名称转换为扩展端的处理方法：

```javascript
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 语句分发处理：

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

资料来源：[CONTRIBUTING.md:60-80]()

## 相关页面

- [快速开始指南](https://github.com/Agent360dk/browser-mcp/wiki/快速开始) — 安装与配置
- [导航与内容工具](https://github.com/Agent360dk/browser-mcp/wiki/导航与内容工具) — 页面导航和内容提取
- [提供商集成](https://github.com/Agent360dk/browser-mcp/wiki/提供商集成) — Stripe、HubSpot 等 API Token 提取
- [HTTP 请求工具](https://github.com/Agent360dk/browser-mcp/wiki/HTTP请求工具) — CORS 绕过请求
- [贡献指南](https://github.com/Agent360dk/browser-mcp/blob/main/CONTRIBUTING.md) — 如何添加新工具

---

## 数据与网络工具

### 相关页面

相关主题：[导航与内容工具](#page-tools-navigation), [交互操作工具](#page-tools-interaction)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp-server/tools.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js) - 工具定义，包含数据获取和网络交互相关工具
- [mcp-server/index.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/index.js) - MCP服务器主逻辑，工具调用处理
- [extension/background.js](https://github.com/Agent360dk/browser-mcp/blob/main/extension/background.js) - Chrome扩展后台脚本，浏览器API调度
- [mcp-server/package.json](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/package.json) - npm包配置
- [README.md](https://github.com/Agent360dk/browser-mcp/blob/main/README.md) - 项目说明文档
</details>

# 数据与网络工具

Browser MCP 提供了一套完整的数据获取与网络交互工具，使 Claude Code 能够从网页中提取内容、捕获数据、监控网络请求，并绕过同源策略限制。这些工具是浏览器自动化的核心组成部分，支持内容抓取、数据提取和跨域请求等常见自动化场景。

## 工具概览

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

| 类别 | 工具数量 | 主要功能 |
|------|----------|----------|
| **内容获取** | 3个 | 页面内容提取、截图、脚本执行 |
| **网络交互** | 3个 | 网络监控、CORS代理、对话框处理 |
| **数据提取** | 2个 | Token提取、用户交互收集 |

资料来源：[mcp-server/tools.js:1-50]()

## 架构设计

### 通信流程

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

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。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `format` | string | 否 | 输出格式：`text`（默认）或 `html` |

**返回值示例（text 格式）：**
```
首页 / 登录 / 产品
欢迎使用 Browser MCP

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

**返回值示例（html 格式）：**
```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

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

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `path` | string | 否 | 文件保存路径，如 `/path/to/screenshot.png` |

**使用说明：**

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

**返回值：**
```json
{
  "base64": "iVBORw0KGgoAAAANSUhEUgAAAAEAAA...",
  "path": "/tmp/screenshot.png"
}
```

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

### browser_execute_script

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

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `code` | string | 是 | 要执行的 JavaScript 代码 |

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

**返回值示例：**
```json
[
  {"href": "https://example.com/about", "text": "关于我们"},
  {"href": "https://example.com/contact", "text": "联系我们"}
]
```

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

## 网络交互工具

### browser_wait_for_network

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

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `timeout` | number | 否 | 超时时间（毫秒），默认 30000 |

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

**返回值：**
```json
{
  "ok": true,
  "message": "Network idle after 1.2s"
}
```

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

### browser_fetch

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

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `url` | string | 是 | 请求目标 URL |
| `method` | string | 否 | HTTP 方法：`GET`（默认）、`POST`、`PUT`、`DELETE` 等 |
| `headers` | object | 否 | 请求头 |
| `body` | string | 否 | 请求体（用于 POST/PUT） |

**返回值：**
```json
{
  "ok": true,
  "status": 200,
  "statusText": "OK",
  "headers": {
    "content-type": "application/json"
  },
  "body": "{\"data\": \"example\"}"
}
```

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

**示例：调用外部 API 获取数据**
```javascript
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）。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `action` | string | 是 | 操作：`accept` 或 `dismiss` |
| `prompt_text` | string | 否 | prompt 对话框的输入文本（仅当 action 为 `accept` 且是 prompt 时需要） |

**返回值：**
```json
{
  "ok": true,
  "dialogType": "confirm",
  "action": "accept"
}
```

**使用示例：**
```javascript
// 接受确认对话框
browser_handle_dialog({ action: "accept" })

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

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

## 数据提取工具

### browser_extract_token

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

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `provider` | string | 是 | 服务提供商名称 |

**支持的提供商：**

| 提供商 | Token 页面 | 说明 |
|--------|------------|------|
| `stripe` | dashboard.stripe.com/apikeys | Stripe Secret Key (sk_live_/sk_test_) |
| `hubspot` | app.hubspot.com/settings/ | HubSpot Private App Access Token |
| `slack` | api.slack.com/apps | Slack Bot User OAuth Token (xoxb-...) |
| `shopify` | admin.shopify.com | Shopify Admin API Token |
| `linkedin` | linkedin.com/developers | LinkedIn OAuth Token |
| `github` | github.com/settings/tokens | GitHub Personal Access Token |

**使用流程：**

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

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

**返回值：**
```json
{
  "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 报告和功能反馈。

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `intent` | string | 否 | 意图类型：`wish`（功能请求）、`use_case`（使用案例）、`bug`（Bug报告）、`info`（一般信息） |
| `title` | string | 否 | 预填的 Issue 标题 |
| `body` | string | 否 | 预填的内容/首条评论草稿 |

**使用场景：**

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

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

**返回值：**
```json
{
  "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. 页面内容抓取

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

**完整示例：**
```javascript
// 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）

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

**完整示例：**
```javascript
// 导航到已登录的内部系统
browser_navigate({ url: "https://internal.company.com" })

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

### 性能注意事项

| 场景 | 建议 | 原因 |
|------|------|------|
| 页面加载等待 | 优先使用 `wait_for_network` | 比固定 timeout 更精确，减少等待时间 |
| 大量截图 | 控制分辨率和格式 | base64 编码可能较大 |
| 脚本执行 | 限制返回数据量 | 避免内存溢出 |
| 网络请求 | 设置合理的 timeout | 避免无限等待 |

## 远程使用与网络配置

> ⚠️ **社区关注点**：有用户报告尝试远程使用 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 先访问目标域名的页面

### 内容获取不完整

**可能原因：**
- 页面使用懒加载，内容未完全渲染
- 需要滚动页面才能加载更多内容

**解决方案：**
```javascript
// 滚动到底部触发懒加载
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_click.md)、[browser_fill](browser_fill.md)、[browser_hover](browser_hover.md)
- **导航工具**：[browser_navigate](browser_navigate.md)、[browser_wait](browser_wait.md)
- **窗口管理**：[browser_new_window](browser_new_window.md)、[browser_close_window](browser_close_window.md)
- **配置与管理**：[browser_about](browser_about.md)、[browser_settings](browser_settings.md)

## 参考资料

| 文件 | 说明 | 相关工具 |
|------|------|----------|
| [mcp-server/tools.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js) | 工具定义文件 | 全部数据与网络工具 |
| [mcp-server/index.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/index.js) | MCP 服务器主逻辑 | 工具调用分发 |
| [extension/background.js](https://github.com/Agent360dk/browser-mcp/blob/main/extension/background.js) | 扩展后台脚本 | 浏览器 API 执行 |
| [README.md](https://github.com/Agent360dk/browser-mcp/blob/main/README.md) | 项目主文档 | 功能概述与安装说明 |

---

## CAPTCHA 解决

### 相关页面

相关主题：[人机交互机制](#page-human-in-loop)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp-server/tools.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js)
- [mcp-server/index.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/index.js)
- [extension/background.js](https://github.com/Agent360dk/browser-mcp/blob/main/extension/background.js)
- [README.md](https://github.com/Agent360dk/browser-mcp/blob/main/README.md)
- [mcp-server/package.json](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/package.json)
</details>

# CAPTCHA 解决

## 概述

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

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

## 工作原理

### 架构流程

```mermaid
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
```

### 组件协作

| 组件 | 角色 | 职责 |
|------|------|------|
| **Claude Code** | AI 控制器 | 决策何时暂停并请求人工介入 |
| **MCP Server** | 协议桥接 | 暴露 `browser_ask_user` 工具给 Claude Code |
| **Extension Background** | 执行层 | 管理浏览器标签页，处理用户交互事件 |
| **Extension Popup** | 用户界面 | 显示交互窗口，收集用户输入 |

资料来源：[extension/background.js](https://github.com/Agent360dk/browser-mcp/blob/main/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` 工具：

```javascript
// 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 或凭证输入。

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `action` | string | 是 | 需要用户执行的具体操作描述 |
| `context` | string | 否 | 额外的上下文信息，帮助用户理解当前状态 |

**返回值：**

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

资料来源：[mcp-server/tools.js:1-50]()

### browser_about

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

| 参数 | 类型 | 必需 | 说明 |
|------|------|------|------|
| `intent` | string | 否 | 意图类型：`wish`（功能请求）、`use_case`（使用案例）、`bug`（问题报告） |
| `title` | string | 否 | 预填的 issue 标题 |
| `body` | string | 否 | 预填的正文内容 |

资料来源：[mcp-server/tools.js:100-150]()

## 最佳实践

### 1. 提前识别 CAPTCHA 场景

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

```javascript
// 导航到可能需要验证的页面
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` 时，提供足够的信息帮助用户快速完成验证：

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

### 3. 处理验证超时

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

| 设置项 | 推荐值 | 说明 |
|--------|--------|------|
| 等待超时 | 120 秒 | 足够用户完成大多数 CAPTCHA |
| 重试次数 | 3 次 | 多次尝试后记录问题并继续 |

## 已知限制

### 安全限制

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

### 技术限制

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

## 相关工具

| 工具名称 | 功能描述 |
|----------|----------|
| `browser_navigate` | 导航到指定 URL |
| `browser_get_page_content` | 获取页面内容用于检测 CAPTCHA |
| `browser_screenshot` | 截图记录验证状态 |
| `browser_ask_user` | 请求人工介入处理验证 |

## 参见

- [安装指南](README.md) — 完整的 Browser MCP 安装流程
- [工具列表](README.md#34-tools) — 所有 34 个浏览器自动化工具
- [使用案例](USE_CASES.md) — 用户分享的真实自动化场景
- [功能愿望单](WISHLIST.md) — 社区请求的功能特性

---

## 人机交互机制

### 相关页面

相关主题：[CAPTCHA 解决](#page-captcha-solving)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp-server/tools.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js)
- [mcp-server/index.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/index.js)
- [extension/popup.html](https://github.com/Agent360dk/browser-mcp/blob/main/extension/popup.html)
- [extension/popup.js](https://github.com/Agent360dk/browser-mcp/blob/main/extension/popup.js)
- [extension/background.js](https://github.com/Agent360dk/browser-mcp/blob/main/extension/background.js)
- [README.md](https://github.com/Agent360dk/browser-mcp/blob/main/README.md)
</details>

# 人机交互机制

Browser MCP 的人机交互机制（Human-in-the-Loop，HITL）是其核心差异化特性之一。与其他浏览器自动化工具不同，Browser MCP 允许 AI 代理在关键决策点暂停执行，请求人类用户的确认、输入或干预，然后根据用户的响应继续自动化流程。这一机制对于需要处理双因素认证（2FA）、验证码（CAPTCHA）、敏感凭证输入以及第三方服务授权等场景至关重要。

## 概述

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

| 工具名称 | 功能描述 | 使用场景 |
|---------|---------|---------|
| `browser_ask_user` | 请求用户确认或输入 | 2FA 验证码、敏感操作确认、凭证输入 |
| `browser_extract_token` | 从提供商页面提取 API Token | Stripe、HubSpot、Slack 等 API 授权 |
| `browser_handle_dialog` | 处理浏览器弹窗对话框 | alert、confirm、prompt 等浏览器对话框 |

资料来源：[mcp-server/tools.js:1-50]()

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

## 核心工具详解

### browser_ask_user

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

```javascript
{
  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]()

#### 使用流程

```mermaid
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 授权流程。

```javascript
{
  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]()

#### 支持的提供商

| 提供商 | Token 类型 | 说明页面 |
|--------|-----------|---------|
| Stripe | `sk_live_...` / `sk_test_...` | dashboard.stripe.com/apikeys |
| HubSpot | Access Token | 应用设置 → Private Apps → Access Token |
| Slack | `xoxb-...` (Bot Token) | OAuth & Permissions 页面 |
| Shopify | Admin API Token | Settings → Apps and sales channels |
| Linear | API Key | Settings → API |
| Notion | Integration Token | My Integrations → 获取 Token |
| Intercom | Access Token | Settings → Developers → OAuth |
| GitHub | Personal Access Token | Settings → Developer settings |

资料来源：[mcp-server/tools.js:191-220]()

### browser_handle_dialog

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

```javascript
{
  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`）包含以下核心区域：

```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]()

### 状态展示

弹窗实时显示以下信息：

| 组件 | 描述 | 更新频率 |
|-----|------|---------|
| Session ID | 当前会话的标识符（颜色编码） | 初始化时 |
| Tab 列表 | 当前会话打开的所有标签页 | 按需更新 |
| Action Log | 最近执行的自动化操作历史 | 实时追加 |
| 连接状态 | MCP 服务器连接状态指示器 | 每 2 秒检测 |

### 交互控制

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

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

## 多会话管理

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

```mermaid
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 扩展和用户界面之间的高效协作。

```mermaid
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 连接：

```javascript
// 扫描端口范围 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 网关运行在局域网服务器上，而浏览器运行在本地机器上时，需要一种方式让扩展能够连接到远程服务器。

```mermaid
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)"

## 配置与参数

### 工具默认参数

| 参数 | 默认值 | 说明 |
|-----|-------|------|
| `options` | `["Yes", "No"]` | 交互按钮选项 |
| `default_response` | `300000` (5分钟) | 自动提交的等待时间 |
| `timeout` | `60000` (1分钟) | 操作超时时间 |

### 环境变量

| 变量 | 说明 | 示例 |
|-----|------|-----|
| `BROWSER_MCP_PORT_RANGE_START` | WebSocket 起始端口 | `9876` |
| `BROWSER_MCP_PORT_RANGE_END` | WebSocket 结束端口 | `9885` |
| `BROWSER_MCP_IDLE_TIMEOUT` | 空闲超时（小时） | `4` |

## 常见问题

### 交互超时

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

### 远程连接失败

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

### 多会话冲突

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

## 最佳实践

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

## 参见

- [快速开始指南](README.md) - 安装与基础配置
- [工具列表](README.md#34-tools) - 完整工具参考
- [贡献指南](CONTRIBUTING.md) - 报告问题与功能请求
- [使用案例](USE_CASES.md) - 社区实践分享
- [愿望清单](WISHLIST.md) - 功能请求跟踪

---

## 第三方服务集成

### 相关页面

相关主题：[数据与网络工具](#page-tools-data)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mcp-server/tools.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js) — 工具定义与提供商页面配置
- [mcp-server/index.js](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/index.js) — MCP 服务器主入口
- [extension/background.js](https://github.com/Agent360dk/browser-mcp/blob/main/extension/background.js) — Chrome 扩展后台服务
- [README.md](https://github.com/Agent360dk/browser-mcp/blob/main/README.md) — 项目说明文档
- [mcp-server/package.json](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/package.json) — npm 包配置
</details>

# 第三方服务集成

## 概述

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

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

资料来源：[README.md](https://github.com/Agent360dk/browser-mcp/blob/main/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](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js)

### 输入参数

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `provider` | string | 是 | 提供商标识符（如 stripe、hubspot） |
| `client_id` | string | 否 | OAuth 客户端 ID（部分提供商需要） |
| `client_secret` | string | 否 | OAuth 客户端密钥（部分提供商需要） |

### 返回值

| 字段 | 类型 | 说明 |
|------|------|------|
| `token` | string | 提取到的 API 令牌 |
| `provider` | string | 提供商名称 |
| `url` | string | 令牌所在页面 URL |

## 支持的提供商

### 提供商列表

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

| 提供商 | 平台类型 | 令牌类型 | 控制台 URL |
|--------|----------|----------|------------|
| Stripe | 支付网关 | Secret Key (sk_live_/sk_test_) | dashboard.stripe.com/apikeys |
| HubSpot | CRM | Access Token | app.hubspot.com/settings/ |
| Slack | 即时通讯 | Bot OAuth Token (xoxb-...) | api.slack.com/apps |
| Shopify | 电商平台 | Admin API 访问令牌 | admin.shopify.com |

### Stripe 集成

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

**提取目标：**
- 生产密钥：`sk_live_` 前缀
- 测试密钥：`sk_test_` 前缀

**使用示例：**

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

资料来源：[mcp-server/tools.js:219-227](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js)

### 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

## 工作原理

### 架构流程

### 令牌提取机制

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

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

资料来源：[mcp-server/tools.js:219-240](https://github.com/Agent360dk/browser-mcp/blob/main/mcp-server/tools.js)

### Provider 配置结构

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

```javascript
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 → ...',
  },
  // ... 更多提供商
};
```

## 集成优势

### 相比其他方案的优点

| 特性 | Browser MCP | Playwright MCP | 其他方案 |
|------|-------------|----------------|----------|
| 浏览器环境 | 真实 Chrome（保留登录状态） | 无头浏览器 | 需重新登录 |
| 提供商集成 | 9 个内置 | 无 | 手动配置 |
| 人类介入 | 支持 2FA/CAPTCHA | 不支持 | 取决于方案 |
| CORS 绕过 | 通过扩展后台请求 | 不适用 | 受限 |

资料来源：[README.md](https://github.com/Agent360dk/browser-mcp/blob/main/README.md)

### 典型使用场景

**场景一：Stripe 退款自动化**

```javascript
// 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 通知发送**

```javascript
// 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` 对象中添加新的提供商条目：

```javascript
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 选项枚举：

```javascript
{
  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 处理分支：

```javascript
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](https://github.com/Agent360dk/browser-mcp/blob/main/extension/background.js)

## 限制与注意事项

### 安全考虑

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

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

资料来源：[社区 Issue #1](https://github.com/Agent360dk/browser-mcp/discussions)

### 技术限制

| 限制 | 说明 | 解决方案 |
|------|------|----------|
| 页面加载延迟 | 部分控制台页面需要较长加载时间 | 使用 `browser_wait` 等待元素 |
| MFA 要求 | 高级安全设置可能需要二次验证 | 通过浏览器手动完成验证步骤 |
| 动态渲染 | 令牌可能通过 JavaScript 动态加载 | 等待网络请求完成后再提取 |

### 版本兼容性

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

## 相关资源

- [工具列表](./tools-list.md) — 所有 34 个浏览器自动化工具完整参考
- [安装指南](./installation.md) — 完整的 Browser MCP 安装配置教程
- [架构说明](./architecture.md) — MCP 服务器与扩展的通信机制详解

---

_本文档最后更新于 v1.16.1 · 由 Agent360 维护_

---

---

## Doramagic 踩坑日志

项目：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