concurrent-browser-mcp

A multi-concurrent browser MCP (Model Context Protocol) server built with Playwright.

中文 | English

Features

• 🚀 Multi-Instance Concurrency: Support running multiple browser instances simultaneously
• 🎯 Instance Management: Dynamically create, manage, and clean up browser instances
• 🔧 Flexible Configuration: Support various browser types and custom configurations
• 🛡️ Resource Management: Automatically clean up timed-out instances to prevent resource leaks
• 🌐 Full Feature Support: Complete browser automation capabilities (navigation, clicking, input, screenshots, etc.)
• 💻 Cross-Platform: Support Chromium, Firefox, WebKit

Installation

Option 1: Install from npm (Recommended)

# Global installation
npm install -g concurrent-browser-mcp

# Or use npx directly (no installation required)
npx concurrent-browser-mcp

Option 2: Build from Source

# Clone repository
git clone https://github.com/sailaoda/concurrent-browser-mcp.git
cd concurrent-browser-mcp

# Install dependencies
npm install

# Build project
npm run build

# Optional: Global link (for local development)
npm link

Option 3: Quick Install Script

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

Quick Start

1. Basic Usage

# Start server (default configuration)
npx concurrent-browser-mcp

# Custom configuration
npx concurrent-browser-mcp --max-instances 25 --browser firefox --headless false

2. MCP Client Configuration

Choose the appropriate configuration based on your installation method:

Using npm global installation or npx

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

Using global installation version

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

Using local build version

If you built from source, you can reference the local build version directly:

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

Or use relative path (if config file and project are in the same directory level):

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

Using npm link version (development mode)

If you used npm link:

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

Command Line Options

Proxy Configuration

concurrent-browser-mcp supports flexible proxy configuration to help you use browser automation features in network environments that require proxies.

Proxy Configuration Methods

1. Specify Proxy via Command Line

# Use specified proxy server
npx concurrent-browser-mcp --proxy http://127.0.0.1:7890

2. Automatic Local Proxy Detection (Enabled by Default)

The system automatically detects proxies in the following order:

• Environment Variables: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY
• Common Proxy Ports: 7890, 1087, 8080, 3128, 8888, 10809, 20171
• System Proxy Settings (macOS): Automatically reads system network settings

# Auto-detection enabled by default (no additional parameters needed)
npx concurrent-browser-mcp

# Explicitly disable auto-detection
npx concurrent-browser-mcp --no-proxy-auto-detect

3. Proxy Settings in MCP Configuration File

Using specified proxy:

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

Disable proxy:

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

Proxy Detection Logs

The proxy detection results will be displayed at startup:

🚀 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  # or shows detected proxy address

Supported Proxy Types

• HTTP proxy: http://proxy-server:port
• HTTPS proxy: https://proxy-server:port
• SOCKS5 proxy: socks5://proxy-server:port

Notes

• Proxy configuration applies to all created browser instances
• Authentication with username/password is not supported
• Proxy can be set via environment variables without manual configuration
• Proxy detection is completed automatically at service startup without affecting runtime performance

Available Tools

Instance Management

• browser_create_instance: Create a new browser instance
• browser_list_instances: List all instances
• browser_close_instance: Close a specific instance
• browser_close_all_instances: Close all instances

Page Navigation

• browser_navigate: Navigate to a specified URL
• browser_go_back: Go back to previous page
• browser_go_forward: Go forward to next page
• browser_refresh: Refresh current page

Page Interaction

• browser_click: Click on page elements
• browser_type: Type text content
• browser_fill: Fill form fields
• browser_select_option: Select dropdown options

Page Information

• browser_get_page_info: Get detailed page information including full HTML content, page statistics, and metadata
• browser_get_element_text: Get element text
• browser_get_element_attribute: Get element attributes
• browser_screenshot: Take page screenshots
• browser_get_markdown: 🆕 Get Markdown content

Wait Operations

• browser_wait_for_element: Wait for element to appear
• browser_wait_for_navigation: Wait for page navigation to complete

JavaScript Execution

• browser_evaluate: Execute JavaScript code

Usage Examples

1. Create Browser Instance

// Create a new Chrome instance
await callTool('browser_create_instance', {
  browserType: 'chromium',
  headless: false,
  viewport: { width: 1920, height: 1080 },
  metadata: {
    name: 'main-browser',
    description: 'Main browser instance'
  }
});

2. Navigation and Interaction

// Navigate to website
await callTool('browser_navigate', {
  instanceId: 'your-instance-id',
  url: 'https://example.com'
});

// Click element
await callTool('browser_click', {
  instanceId: 'your-instance-id',
  selector: 'button.submit'
});

// Input text
await callTool('browser_type', {
  instanceId: 'your-instance-id',
  selector: 'input[name="search"]',
  text: 'search query'
});

3. Get Page Information

// Take screenshot
await callTool('browser_screenshot', {
  instanceId: 'your-instance-id',
  fullPage: true
});

// Get page information
await callTool('browser_get_page_info', {
  instanceId: 'your-instance-id'
});

4. Concurrent Operations

// Create multiple instances for parallel processing
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' } })
]);

// Navigate to different pages in parallel
await Promise.all(instances.map(async (instance, index) => {
  await callTool('browser_navigate', {
    instanceId: instance.data.instanceId,
    url: `https://example${index + 1}.com`
  });
}));

Architecture Design

┌─────────────────────────────────────────────────────────────────┐
│                         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)      │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

Real Functionality Testing

In addition to simulation demo scripts, we also provide real browser functionality test scripts that let you see actual screenshot results:

🧪 Run Real Tests

# Run real browser screenshot test
node test-real-screenshot.js

This test script will:

1. Start real browser: Using Chromium engine
2. Visit websites: Navigate to example.com and github.com
3. Save screenshots: Generate real PNG screenshot files
4. File output: Generate screenshot files in current directory

📸 Test Output Example

🚀 Starting real browser screenshot test...
✅ Browser started
✅ Page created
🌐 Navigating to https://example.com...
✅ Page loaded successfully
📸 Taking screenshot and saving as screenshot-2025-07-19T11-04-18-660Z.png...
✅ Screenshot saved: screenshot-2025-07-19T11-04-18-660Z.png
📊 File size: 23.57 KB
📂 File location: /path/to/screenshot-2025-07-19T11-04-18-660Z.png
🌐 Visiting https://github.com...
✅ github screenshot saved: screenshot-github-2025-07-19T11-04-18-660Z.png (265.99 KB)
🛑 Browser closed

🖼️ View Screenshot Files

After testing, you can find actual screenshot files in the project directory:

# View generated screenshot files
ls -la screenshot-*.png

# Open in system default image viewer
open screenshot-*.png    # macOS
start screenshot-*.png   # Windows
xdg-open screenshot-*.png # Linux

Differences from Traditional MCP Browser Servers

Development Guide

Local Development Environment Setup

# 1. Clone project
git clone https://github.com/sailaoda/concurrent-browser-mcp.git
cd concurrent-browser-mcp

# 2. Install dependencies
npm install

# 3. Build project
npm run build

# 4. Local link (optional, for global command testing)
npm link

Available npm Scripts

# Build TypeScript project
npm run build

# Development mode (file watching)
npm run dev

# Run code linting
npm run lint

# Fix code formatting issues
npm run lint:fix

# Clean build artifacts
npm run clean

# Run tests
npm test

Project Structure

concurrent-browser-mcp/
├── src/                    # Source code directory
│   ├── index.ts           # CLI entry point
│   ├── server.ts          # MCP server main logic
│   ├── browser-manager.ts # Browser instance manager
│   └── tools.ts           # MCP tool definitions and implementation
├── dist/                  # Build artifacts directory
├── assets/                # Static resources directory
├── examples/              # Example scripts
├── test-real-screenshot.js # Real test script
├── config.example.json    # Configuration example
├── package.json           # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md             # Project documentation

Using Local Build Version

After building, you can use the local version in several ways:

Option 1: Run build files directly

# Run built files
node dist/index.js --max-instances 20

# Use absolute path in MCP configuration
{
  "mcpServers": {
    "concurrent-browser": {
      "command": "node",
      "args": ["/absolute/path/to/concurrent-browser-mcp/dist/index.js", "--max-instances", "20"]
    }
  }
}

Option 2: Use npm link (recommended for development)

# Execute link in project root directory
npm link

# Now you can use it like a global package
concurrent-browser-mcp --max-instances 20

# Use in MCP configuration
{
  "mcpServers": {
    "concurrent-browser": {
      "command": "concurrent-browser-mcp",
      "args": ["--max-instances", "20"]
    }
  }
}

Option 3: Use in project directory

# Run directly in project directory
cd /path/to/concurrent-browser-mcp
npm run build
node dist/index.js

# MCP configuration using relative path
{
  "mcpServers": {
    "concurrent-browser": {
      "command": "node",
      "args": ["./concurrent-browser-mcp/dist/index.js"],
      "cwd": "/parent/directory/path"
    }
  }
}

Testing and Debugging

# Run real browser tests
node test-real-screenshot.js

# Run simulated MCP call tests
node examples/demo.js

# Start development server (with debug output)
node dist/index.js --max-instances 5 --browser chromium --headless false

Contributing Guidelines

1. Fork this project
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add some amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open Pull Request