concurrent-browser-mcp

v1.6.0

Published

5 months ago

A concurrent browser MCP server that supports multiple parallel browser instances

0High
0Medium
0Low

sailaoda

mcp browser automation playwright concurrent parallel

Concurrent Browser MCP

一个支持多并发的浏览器 MCP (Model Context Protocol) 服务器，基于 Playwright 构建。

中文 | English

功能特点

🚀 多实例并发: 支持同时运行多个浏览器实例
🎯 实例管理: 动态创建、管理和清理浏览器实例
🔧 灵活配置: 支持多种浏览器类型和自定义配置
🛡️ 资源管理: 自动清理超时的实例，防止资源泄漏
🌐 全功能支持: 完整的浏览器自动化功能（导航、点击、输入、截图等）
💻 跨平台: 支持 Chromium、Firefox、WebKit

安装

方式一：从 npm 安装（推荐）

# 全局安装
npm install -g concurrent-browser-mcp

# 或者直接使用 npx（无需安装）
npx concurrent-browser-mcp

方式二：从源码构建

# 克隆仓库
git clone https://github.com/sailaoda/concurrent-browser-mcp.git
cd concurrent-browser-mcp

# 安装依赖
npm install

# 构建项目
npm run build

# 可选：全局链接（用于本地开发）
npm link

方式三：快速安装脚本

git clone https://github.com/sailaoda/concurrent-browser-mcp.git
cd concurrent-browser-mcp
./install.sh

快速开始

1. 基础用法

# 启动服务器（默认配置）
npx concurrent-browser-mcp

# 自定义配置
npx concurrent-browser-mcp --max-instances 25 --browser firefox --headless false

2. MCP 客户端配置

根据您的安装方式选择相应的配置：

使用 npm 全局安装或 npx

{
  "mcpServers": {
    "concurrent-browser": {
      "command": "npx",
      "args": ["concurrent-browser-mcp", "--max-instances", "20"]
    }
  }
}

使用全局安装版本

{
  "mcpServers": {
    "concurrent-browser": {
      "command": "concurrent-browser-mcp",
      "args": ["--max-instances", "20"]
    }
  }
}

使用本地构建版本

如果您从源码构建，可以直接引用本地构建的版本：

{
  "mcpServers": {
    "concurrent-browser": {
      "command": "node",
      "args": ["/path/to/concurrent-browser-mcp/dist/index.js", "--max-instances", "20"],
      "cwd": "/path/to/concurrent-browser-mcp"
    }
  }
}

或者使用相对路径（如果配置文件和项目在同一目录层级）：

{
  "mcpServers": {
    "concurrent-browser": {
      "command": "node",
      "args": ["./concurrent-browser-mcp/dist/index.js", "--max-instances", "20"]
    }
  }
}

使用 npm link 版本（开发模式）

如果您使用了 npm link：

{
  "mcpServers": {
    "concurrent-browser": {
      "command": "concurrent-browser-mcp",
      "args": ["--max-instances", "20"]
    }
  }
}

命令行选项

| 选项 | 描述 | 默认值 | |------|------|--------| | -m, --max-instances <number> | 最大实例数 | 20 | | -t, --instance-timeout <number> | 实例超时时间（分钟） | 30 | | -c, --cleanup-interval <number> | 清理间隔（分钟） | 5 | | --browser <browser> | 默认浏览器类型 (chromium/firefox/webkit) | chromium | | --headless | 默认无头模式 | true | | --width <number> | 默认视口宽度 | 1280 | | --height <number> | 默认视口高度 | 720 | | --user-agent <string> | 默认用户代理 | - | | --proxy <string> | 代理服务器地址 (例如: http://127.0.0.1:7890) | - | | --no-proxy-auto-detect | 禁用代理自动检测 | false | | --ignore-https-errors | 忽略 HTTPS 错误 | false | | --bypass-csp | 绕过 CSP | false |

代理配置

concurrent-browser-mcp 支持灵活的代理配置，帮助您在需要代理的网络环境中正常使用浏览器自动化功能。

代理配置方式

1. 命令行指定代理

# 使用指定的代理服务器
npx concurrent-browser-mcp --proxy http://127.0.0.1:7890

2. 自动检测本地代理（默认启用）

系统会自动按以下顺序检测代理：

环境变量: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY
常见代理端口: 7890, 1087, 8080, 3128, 8888, 10809, 20171
系统代理设置 (macOS): 自动读取系统网络设置

# 默认启用自动检测（无需额外参数）
npx concurrent-browser-mcp

# 明确禁用自动检测
npx concurrent-browser-mcp --no-proxy-auto-detect

3. MCP 配置文件中的代理设置

使用指定代理：

{
  "mcpServers": {
    "concurrent-browser": {
      "command": "npx",
      "args": ["concurrent-browser-mcp", "--proxy", "http://127.0.0.1:7890"]
    }
  }
}

禁用代理：

{
  "mcpServers": {
    "concurrent-browser": {
      "command": "npx", 
      "args": ["concurrent-browser-mcp", "--no-proxy-auto-detect"]
    }
  }
}

代理检测日志

启动时会显示代理检测结果：

🚀 Starting Concurrent Browser MCP Server...
Max instances: 20
Default browser: chromium
Headless mode: yes
Viewport size: 1280x720
Instance timeout: 30 minutes
Cleanup interval: 5 minutes
Proxy: Auto-detection enabled  # 或显示检测到的代理地址

支持的代理类型

HTTP 代理：http://proxy-server:port
HTTPS 代理：https://proxy-server:port
SOCKS5 代理：socks5://proxy-server:port

注意事项

代理配置会应用到所有创建的浏览器实例
不支持需要用户名密码认证的代理
可以通过环境变量设置代理，无需手动配置
代理检测会在服务启动时自动完成，不影响运行性能

可用工具

工具分类图

实例管理

browser_create_instance: 创建新的浏览器实例
browser_list_instances: 列出所有实例
browser_close_instance: 关闭指定实例
browser_close_all_instances: 关闭所有实例

页面导航

browser_navigate: 导航到指定URL
browser_go_back: 返回上一页
browser_go_forward: 前进到下一页
browser_refresh: 刷新当前页面

页面交互

browser_click: 点击页面元素
browser_type: 在元素中输入文本
browser_fill: 填充表单字段
browser_select_option: 选择下拉选项

页面信息

browser_get_page_info: 获取页面信息
browser_get_element_text: 获取元素文本
browser_get_element_attribute: 获取元素属性
browser_screenshot: 截取页面截图
browser_get_markdown: 获取Markdown内容

等待操作

browser_wait_for_element: 等待元素出现
browser_wait_for_navigation: 等待页面导航完成

JavaScript 执行

browser_evaluate: 执行 JavaScript 代码

使用示例

1. 创建浏览器实例

// 创建一个新的 Chrome 实例
await callTool('browser_create_instance', {
  browserType: 'chromium',
  headless: false,
  viewport: { width: 1920, height: 1080 },
  metadata: {
    name: 'main-browser',
    description: '主要浏览器实例'
  }
});

2. 导航和交互

// 导航到网站
await callTool('browser_navigate', {
  instanceId: 'your-instance-id',
  url: 'https://example.com'
});

// 点击按钮
await callTool('browser_click', {
  instanceId: 'your-instance-id',
  selector: '#submit-button'
});

// 输入文本
await callTool('browser_type', {
  instanceId: 'your-instance-id',
  selector: '#username',
  text: 'myusername'
});

3. 截图和信息获取

// 截取页面截图
await callTool('browser_screenshot', {
  instanceId: 'your-instance-id',
  fullPage: true,
  type: 'png'
});

// 获取页面信息
await callTool('browser_get_page_info', {
  instanceId: 'your-instance-id'
});

4. 并发操作

// 创建多个实例并行处理
const instances = await Promise.all([
  callTool('browser_create_instance', { metadata: { name: 'worker-1' } }),
  callTool('browser_create_instance', { metadata: { name: 'worker-2' } }),
  callTool('browser_create_instance', { metadata: { name: 'worker-3' } })
]);

// 并行导航到不同的页面
await Promise.all(instances.map(async (instance, index) => {
  await callTool('browser_navigate', {
    instanceId: instance.data.instanceId,
    url: `https://example${index + 1}.com`
  });
}));

架构设计

┌─────────────────────────────────────────────────────────────────┐
│                         MCP Client                              │
├─────────────────────────────────────────────────────────────────┤
│                    Concurrent Browser MCP Server                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  Browser Tools  │  │ Browser Manager │  │  MCP Server     │  │
│  │                 │  │                 │  │                 │  │
│  │ - Tool Defs     │  │ - Instance Mgmt │  │ - Request       │  │
│  │ - Execution     │  │ - Lifecycle     │  │   Handling      │  │
│  │ - Validation    │  │ - Cleanup       │  │ - Error Mgmt    │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
├─────────────────────────────────────────────────────────────────┤
│                        Playwright                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │   Browser 1     │  │   Browser 2     │  │   Browser N     │  │
│  │   (Chromium)    │  │   (Firefox)     │  │   (WebKit)      │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

真实功能测试

除了模拟演示脚本，我们还提供了真实的浏览器功能测试脚本，让您可以看到实际的截图效果：

🧪 运行真实测试

# 运行真实浏览器截图测试
node test-real-screenshot.js

这个测试脚本会：

启动真实浏览器: 使用 Chromium 引擎
访问网站: 导航到 example.com 和 github.com
截图保存: 生成真实的 PNG 截图文件
文件输出: 在当前目录生成截图文件

📸 测试输出示例

🚀 启动真实浏览器截图测试...
✅ 浏览器已启动
✅ 页面已创建
🌐 正在导航到 https://example.com...
✅ 页面加载完成
📸 正在截图并保存为 screenshot-2025-07-19T11-04-18-660Z.png...
✅ 截图已保存: screenshot-2025-07-19T11-04-18-660Z.png
📊 文件大小: 23.57 KB
📂 文件位置: /path/to/screenshot-2025-07-19T11-04-18-660Z.png
🌐 正在访问 https://github.com...
✅ github 截图已保存: screenshot-github-2025-07-19T11-04-18-660Z.png (265.99 KB)
🛑 浏览器已关闭

🖼️ 查看截图文件

测试完成后，您可以在项目目录中找到实际的截图文件：

# 查看生成的截图文件
ls -la screenshot-*.png

# 在系统默认图片查看器中打开
open screenshot-*.png    # macOS
start screenshot-*.png   # Windows
xdg-open screenshot-*.png # Linux

与传统 MCP 浏览器服务器的区别

| 特性 | 传统 MCP 浏览器服务器 | Concurrent Browser MCP | |------|---------------------|----------------------| | 实例管理 | 单实例 | 多实例并发 | | 资源隔离 | 无 | 完全隔离 | | 并发处理 | 串行 | 并行 | | 实例生命周期 | 手动管理 | 自动管理 | | 资源清理 | 手动 | 自动 | | 可扩展性 | 有限 | 高度可扩展 |

开发指南

本地开发环境搭建

# 1. 克隆项目
git clone https://github.com/sailaoda/concurrent-browser-mcp.git
cd concurrent-browser-mcp

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 本地链接（可选，用于全局命令测试）
npm link

可用的 npm 脚本

# 构建 TypeScript 项目
npm run build

# 开发模式（文件监听）
npm run dev

# 运行代码检查
npm run lint

# 修复代码格式问题
npm run lint:fix

# 清理构建产物
npm run clean

# 运行测试
npm test

项目结构

concurrent-browser-mcp/
├── src/                    # 源代码目录
│   ├── index.ts           # CLI 入口
│   ├── server.ts          # MCP 服务器主逻辑
│   ├── browser-manager.ts # 浏览器实例管理器
│   └── tools.ts           # MCP 工具定义和实现
├── dist/                  # 构建产物目录
├── assets/                # 静态资源目录
├── examples/              # 示例脚本
├── test-real-screenshot.js # 真实测试脚本
├── config.example.json    # 配置示例
├── package.json           # 项目配置
├── tsconfig.json         # TypeScript 配置
└── README.md             # 项目文档

使用本地构建版本

构建完成后，您可以通过以下几种方式使用本地版本：

方式一：直接运行构建文件

# 运行构建后的文件
node dist/index.js --max-instances 20

# 在 MCP 配置中使用绝对路径
{
  "mcpServers": {
    "concurrent-browser": {
      "command": "node",
      "args": ["/absolute/path/to/concurrent-browser-mcp/dist/index.js", "--max-instances", "20"]
    }
  }
}

方式二：使用 npm link（推荐开发使用）

# 在项目根目录执行链接
npm link

# 现在可以像全局包一样使用
concurrent-browser-mcp --max-instances 20

# 在 MCP 配置中使用
{
  "mcpServers": {
    "concurrent-browser": {
      "command": "concurrent-browser-mcp",
      "args": ["--max-instances", "20"]
    }
  }
}

方式三：在项目目录中使用

# 在项目目录中直接运行
cd /path/to/concurrent-browser-mcp
npm run build
node dist/index.js

# MCP 配置使用相对路径
{
  "mcpServers": {
    "concurrent-browser": {
      "command": "node",
      "args": ["./concurrent-browser-mcp/dist/index.js"],
      "cwd": "/parent/directory/path"
    }
  }
}

测试和调试

# 运行真实浏览器测试
node test-real-screenshot.js

# 运行模拟 MCP 调用测试
node examples/demo.js

# 启动开发服务器（带调试输出）
node dist/index.js --max-instances 5 --browser chromium --headless false

贡献指南

Fork 本项目
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m 'Add some amazing feature')
推送到分支 (git push origin feature/amazing-feature)
开启 Pull Request

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Concurrent Browser MCP

功能特点

安装

方式一：从 npm 安装（推荐）

方式二：从源码构建

方式三：快速安装脚本

快速开始

1. 基础用法

2. MCP 客户端配置

使用 npm 全局安装或 npx

使用全局安装版本

使用本地构建版本

使用 npm link 版本（开发模式）

命令行选项

代理配置

代理配置方式

1. 命令行指定代理

2. 自动检测本地代理（默认启用）

3. MCP 配置文件中的代理设置

代理检测日志

支持的代理类型

注意事项

可用工具

实例管理

页面导航

页面交互

页面信息

等待操作

JavaScript 执行

使用示例

1. 创建浏览器实例

2. 导航和交互

3. 截图和信息获取

4. 并发操作

架构设计

真实功能测试

🧪 运行真实测试

📸 测试输出示例

🖼️ 查看截图文件

与传统 MCP 浏览器服务器的区别

开发指南

本地开发环境搭建

可用的 npm 脚本

项目结构

使用本地构建版本

方式一：直接运行构建文件

方式二：使用 npm link（推荐开发使用）

方式三：在项目目录中使用

测试和调试

贡献指南