Concurrent Browser MCP

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

功能特点

• 🚀 多实例并发: 支持同时运行多个浏览器实例
• 🎯 实例管理: 动态创建、管理和清理浏览器实例
• 🔧 灵活配置: 支持多种浏览器类型和自定义配置
• 🛡️ 资源管理: 自动清理超时的实例，防止资源泄漏
• 🌐 全功能支持: 完整的浏览器自动化功能（导航、点击、输入、截图等）
• 💻 跨平台: 支持 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>	默认用户代理	-
--ignore-https-errors	忽略 HTTPS 错误	false
--bypass-csp	绕过 CSP	false

可用工具

实例管理

• 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

这个测试脚本会：

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

📸 测试输出示例

🚀 启动真实浏览器截图测试...
✅ 浏览器已启动
✅ 页面已创建
🌐 正在导航到 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

贡献指南

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