A concurrent browser MCP server that supports multiple parallel browser instances
npm install concurrent-browser-mcp一个支持多并发的浏览器 MCP (Model Context Protocol) 服务器，基于 Playwright 构建。
中文 | English
- 🚀 多实例并发: 支持同时运行多个浏览器实例
- 🎯 实例管理: 动态创建、管理和清理浏览器实例
- 🔧 灵活配置: 支持多种浏览器类型和自定义配置
- 🛡️ 资源管理: 自动清理超时的实例，防止资源泄漏
- 🌐 全功能支持: 完整的浏览器自动化功能（导航、点击、输入、截图等）
- 💻 跨平台: 支持 Chromium、Firefox、WebKit
``bash全局安装
npm install -g concurrent-browser-mcp
$3
bash
克隆仓库
git clone https://github.com/sailaoda/concurrent-browser-mcp.git
cd concurrent-browser-mcp安装依赖
npm install构建项目
npm run build可选：全局链接（用于本地开发）
npm link
`$3
bash
git clone https://github.com/sailaoda/concurrent-browser-mcp.git
cd concurrent-browser-mcp
./install.sh
`快速开始
$3
bash
启动服务器（默认配置）
npx concurrent-browser-mcp自定义配置
npx concurrent-browser-mcp --max-instances 25 --browser firefox --headless false
`$3
根据您的安装方式选择相应的配置：
#### 使用 npm 全局安装或 npx
json
{
"mcpServers": {
"concurrent-browser": {
"command": "npx",
"args": ["concurrent-browser-mcp", "--max-instances", "20"]
}
}
}
`#### 使用全局安装版本
json
{
"mcpServers": {
"concurrent-browser": {
"command": "concurrent-browser-mcp",
"args": ["--max-instances", "20"]
}
}
}
`#### 使用本地构建版本
如果您从源码构建，可以直接引用本地构建的版本：
json
{
"mcpServers": {
"concurrent-browser": {
"command": "node",
"args": ["/path/to/concurrent-browser-mcp/dist/index.js", "--max-instances", "20"],
"cwd": "/path/to/concurrent-browser-mcp"
}
}
}
`或者使用相对路径（如果配置文件和项目在同一目录层级）：
json
{
"mcpServers": {
"concurrent-browser": {
"command": "node",
"args": ["./concurrent-browser-mcp/dist/index.js", "--max-instances", "20"]
}
}
}
`#### 使用 npm link 版本（开发模式）
如果您使用了
：`json
{
"mcpServers": {
"concurrent-browser": {
"command": "concurrent-browser-mcp",
"args": ["--max-instances", "20"]
}
}
}
`命令行选项
| 选项 | 描述 | 默认值 |
|------|------|--------|
|
| 最大实例数 | 20 |
| -t, --instance-timeout | 实例超时时间（分钟） | 30 |
| -c, --cleanup-interval | 清理间隔（分钟） | 5 |
| --browser | 默认浏览器类型 (chromium/firefox/webkit) | chromium |
| --headless | 默认无头模式 | true |
| --width | 默认视口宽度 | 1280 |
| --height | 默认视口高度 | 720 |
| --user-agent | 默认用户代理 | - |
| --proxy | 代理服务器地址 (例如: http://127.0.0.1:7890) | - |
| --no-proxy-auto-detect | 禁用代理自动检测 | false |
| --ignore-https-errors | 忽略 HTTPS 错误 | false |
| --bypass-csp | 绕过 CSP | false |代理配置
concurrent-browser-mcp 支持灵活的代理配置，帮助您在需要代理的网络环境中正常使用浏览器自动化功能。
$3
#### 1. 命令行指定代理
`bash
使用指定的代理服务器
npx concurrent-browser-mcp --proxy http://127.0.0.1:7890
`#### 2. 自动检测本地代理（默认启用）
系统会自动按以下顺序检测代理：
- 环境变量:
, HTTPS_PROXY, ALL_PROXY
- 常见代理端口: 7890, 1087, 8080, 3128, 8888, 10809, 20171
- 系统代理设置 (macOS): 自动读取系统网络设置bash
默认启用自动检测（无需额外参数）
npx concurrent-browser-mcp明确禁用自动检测
npx concurrent-browser-mcp --no-proxy-auto-detect
`#### 3. MCP 配置文件中的代理设置
使用指定代理：
json
{
"mcpServers": {
"concurrent-browser": {
"command": "npx",
"args": ["concurrent-browser-mcp", "--proxy", "http://127.0.0.1:7890"]
}
}
}
`禁用代理：
json
{
"mcpServers": {
"concurrent-browser": {
"command": "npx",
"args": ["concurrent-browser-mcp", "--no-proxy-auto-detect"]
}
}
}
`$3
启动时会显示代理检测结果：
🚀 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 # 或显示检测到的代理地址
$3
- HTTP 代理：
- HTTPS 代理：
- SOCKS5 代理：$3
- 代理配置会应用到所有创建的浏览器实例
- 不支持需要用户名密码认证的代理
- 可以通过环境变量设置代理，无需手动配置
- 代理检测会在服务启动时自动完成，不影响运行性能可用工具
$3
-
: 创建新的浏览器实例
- browser_list_instances: 列出所有实例
- browser_close_instance: 关闭指定实例
- browser_close_all_instances: 关闭所有实例$3
-
browser_navigate: 导航到指定URL
- browser_go_back: 返回上一页
- browser_go_forward: 前进到下一页
- browser_refresh: 刷新当前页面$3
-
browser_click: 点击页面元素
- browser_type: 在元素中输入文本
- browser_fill: 填充表单字段
- browser_select_option: 选择下拉选项$3
-
browser_get_page_info: 获取页面信息
- browser_get_element_text: 获取元素文本
- browser_get_element_attribute: 获取元素属性
- browser_screenshot: 截取页面截图
- browser_get_markdown: 获取Markdown内容$3
-
browser_wait_for_element: 等待元素出现
- browser_wait_for_navigation: 等待页面导航完成$3
-
browser_evaluate: 执行 JavaScript 代码使用示例
$3
`javascript
// 创建一个新的 Chrome 实例
await callTool('browser_create_instance', {
browserType: 'chromium',
headless: false,
viewport: { width: 1920, height: 1080 },
metadata: {
name: 'main-browser',
description: '主要浏览器实例'
}
});
`$3
javascript
// 导航到网站
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
javascript
// 截取页面截图
await callTool('browser_screenshot', {
instanceId: 'your-instance-id',
fullPage: true,
type: 'png'
});// 获取页面信息
await callTool('browser_get_page_info', {
instanceId: 'your-instance-id'
});
`$3
javascript
// 创建多个实例并行处理
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) │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
真实功能测试
除了模拟演示脚本，我们还提供了真实的浏览器功能测试脚本，让您可以看到实际的截图效果：
$3
bash
运行真实浏览器截图测试
node test-real-screenshot.js
`这个测试脚本会：
1. 启动真实浏览器: 使用 Chromium 引擎
2. 访问网站: 导航到 example.com 和 github.com
3. 截图保存: 生成真实的 PNG 截图文件
4. 文件输出: 在当前目录生成截图文件
$3
🚀 启动真实浏览器截图测试...
✅ 浏览器已启动
✅ 页面已创建
🌐 正在导航到 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)
🛑 浏览器已关闭
$3
测试完成后，您可以在项目目录中找到实际的截图文件：
bash
查看生成的截图文件
ls -la screenshot-*.png在系统默认图片查看器中打开
open screenshot-*.png # macOS
start screenshot-*.png # Windows
xdg-open screenshot-*.png # Linux
`与传统 MCP 浏览器服务器的区别
| 特性 | 传统 MCP 浏览器服务器 | Concurrent Browser MCP |
|------|---------------------|----------------------|
| 实例管理 | 单实例 | 多实例并发 |
| 资源隔离 | 无 | 完全隔离 |
| 并发处理 | 串行 | 并行 |
| 实例生命周期 | 手动管理 | 自动管理 |
| 资源清理 | 手动 | 自动 |
| 可扩展性 | 有限 | 高度可扩展 |
开发指南
$3
bash
1. 克隆项目
git clone https://github.com/sailaoda/concurrent-browser-mcp.git
cd concurrent-browser-mcp2. 安装依赖
npm install3. 构建项目
npm run build4. 本地链接（可选，用于全局命令测试）
npm link
`$3
bash
构建 TypeScript 项目
npm run build开发模式（文件监听）
npm run dev运行代码检查
npm run lint修复代码格式问题
npm run lint:fix清理构建产物
npm run clean运行测试
npm test
`$3
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 # 项目文档
$3
构建完成后，您可以通过以下几种方式使用本地版本：
#### 方式一：直接运行构建文件
bash
运行构建后的文件
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（推荐开发使用）
bash
在项目根目录执行链接
npm link现在可以像全局包一样使用
concurrent-browser-mcp --max-instances 20在 MCP 配置中使用
{
"mcpServers": {
"concurrent-browser": {
"command": "concurrent-browser-mcp",
"args": ["--max-instances", "20"]
}
}
}
`#### 方式三：在项目目录中使用
bash
在项目目录中直接运行
cd /path/to/concurrent-browser-mcp
npm run build
node dist/index.jsMCP 配置使用相对路径
{
"mcpServers": {
"concurrent-browser": {
"command": "node",
"args": ["./concurrent-browser-mcp/dist/index.js"],
"cwd": "/parent/directory/path"
}
}
}
`$3
bash
运行真实浏览器测试
node test-real-screenshot.js运行模拟 MCP 调用测试
node examples/demo.js启动开发服务器（带调试输出）
node dist/index.js --max-instances 5 --browser chromium --headless false
`$3
1. Fork 本项目
2. 创建功能分支 (
)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature`)