Concurrent Browser Mcp

concurrent-browser-mcp

Playwright で構築された、複数のブラウザーインスタンスを並行して実行できる MCP（Model Context Protocol）サーバーです。

中文 | English

特長

• 🚀 複数インスタンスの並行実行：複数のブラウザーインスタンスを同時に実行できます
• 🎯 インスタンス管理：ブラウザーインスタンスの作成、管理、クリーンアップを動的に行えます
• 🔧 柔軟な設定：さまざまなブラウザータイプやカスタム設定に対応します
• 🛡️ リソース管理：タイムアウトしたインスタンスを自動的にクリーンアップし、リソースリークを防ぎます
• 🌐 全機能に対応：ブラウザー自動化の全機能（ナビゲーション、クリック、入力、スクリーンショットなど）を利用できます
• 💻 クロスプラットフォーム：Chromium、Firefox、WebKit に対応します

インストール

方法 1：npm からインストール（推奨）

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

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

方法 2：ソースからビルド

# 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

方法 3：クイックインストールスクリプト

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

クイックスタート

1. 基本的な使い方

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

# Custom configuration
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. コマンドラインでプロキシを指定する

# Use specified proxy server
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）：システムのネットワーク設定を自動的に読み取ります

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

対応するプロキシタイプ

• 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：HTML コンテンツ全体、ページ統計、メタデータなど、詳細なページ情報を取得します
• 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. ブラウザーインスタンスの作成

// 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. ナビゲーションと操作

// 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. ページ情報の取得

// 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. 並行操作

// 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`
  });
}));

アーキテクチャ設計

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

実際の機能テスト

シミュレーション用のデモスクリプトに加えて、実際のスクリーンショットを確認できる、実際のブラウザー機能をテストするスクリプトも用意しています。

🧪 実際のテストを実行

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

このテストスクリプトでは、次の処理を行います。

1. 実際のブラウザーを起動：Chromium エンジンを使用します
2. ウェブサイトにアクセス：example.com と github.com に移動します
3. スクリーンショットを保存：実際の PNG スクリーンショットファイルを生成します
4. ファイルを出力：現在のディレクトリにスクリーンショットファイルを生成します

📸 テスト出力例

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

従来の MCP ブラウザーサーバーとの違い

機能	従来の MCP ブラウザーサーバー	並行ブラウザー MCP
インスタンス管理	単一インスタンス	複数インスタンスの同時実行
リソースの分離	なし	完全に分離
並行処理	逐次	並列
インスタンスのライフサイクル	手動管理	自動管理
リソースのクリーンアップ	手動	自動
スケーラビリティ	限定的	高いスケーラビリティ

開発ガイド

ローカル開発環境のセットアップ

# 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

利用可能な npm スクリプト

# 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

プロジェクト構成

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

ローカルビルド版の使用

ビルド後、いくつかの方法でローカル版を使用できます。

オプション 1：ビルドファイルを直接実行

# 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"]
    }
  }
}

オプション 2：npm link を使用（開発時に推奨）

# 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"]
    }
  }
}

オプション 3：プロジェクトディレクトリ内で使用

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

テストとデバッグ

# 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

コントリビューションガイドライン

1. このプロジェクトをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します