Chrome Debug MCP

🚀 Chrome Debug MCP Server

Chrome Debug MCP Serverは、Chromeブラウザの自動化を目的としたModel Context Protocol (MCP) サーバーです。Chromeのデバッグポートに接続し、ログインセッションを維持したままブラウザの自動化を実現します。

🚀 クイックスタート

オプション1: 直接使用 (推奨)

npxを使用して起動することができ、インストールは不要です。

# 1. Chromeをデバッグモードで起動
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# 2. MCPサーバーを直接実行
npx chrome-debug-mcp

オプション2: ローカル開発

git clone https://github.com/rainmenxia/chrome-debug-mcp.git
cd chrome-debug-mcp
npm install
npm run build
npm start

✨ 主な機能

• ✅ Chromeデバッグポート接続：標準のChrome DevTools Protocolに基づいており、拡張機能は不要です。
• 🏢 エンタープライズグレードのデプロイ：依存関係がなく、Chromeウェブストアの承認も不要です。
• 📱 インテリジェントなタブ管理：同じドメインのタブを再利用し、重複したウェブサイトの開き方を避けます。
• 🖼️ リアルタイムスクリーンショットフィードバック：各操作後に自動的にスクリーンショットを撮り、視覚的なフィードバックを提供します。
• 🌐 ネットワークアクティビティ監視：ページの読み込み完了を自動的に待機します。
• 🐳 ネイティブDockerサポート：コンテナ化されたChromeインスタンスを完全にサポートし、拡張機能の制限がありません。
• ⚡ 2ステップでの起動：Chromeをデバッグモードで起動し、npx chrome-debug-mcpを実行するだけで、複雑なインストールは不要です。
• 🔍 スマートなブラウザ検出：ローカルおよびDocker環境のChromeインスタンスを自動的に検出します。

📦 インストール

1. Chromeデバッグモードを開始 (必須)

サーバーは、デバッグポートが有効になっているChromeインスタンスに接続する必要があります。

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows
chrome.exe --remote-debugging-port=9222 --user-data-dir=c:\temp\chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

⚠️ 重要提示

• --user-data-dirパラメータは一時ディレクトリを指し、Chromeがデバッグモードで起動することを保証します。
• 起動後、通常通りウェブサイトにログインでき、ログインセッションは保持されます。
• サーバーはこのChromeインスタンスを再利用するため、再ログインする必要はありません。

2. MCPクライアントを設定

MCPクライアントに以下の設定を追加します。

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

💡 使用建议

グローバルインストール:

npm install -g chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "chrome-debug-mcp"
    }
  }
}

ローカルプロジェクトインストール:

npm install chrome-debug-mcp

{
  "mcpServers": {
    "browser-automation": {
      "command": "npx",
      "args": ["chrome-debug-mcp"]
    }
  }
}

💻 使用例

基本的な使用法

以下は利用可能なツールの使用例です。

1. launch_browser

Chromeのデバッグポートに接続し、ブラウザセッションを初期化します。

{
  "name": "launch_browser",
  "arguments": {
    "remote_host": "http://localhost:9222"  // オプション
  }
}

2. navigate_to

指定されたURLに移動し、インテリジェントなタブ管理を行います。

{
  "name": "navigate_to", 
  "arguments": {
    "url": "https://example.com"
  }
}

3. click

指定された座標でクリックします。

{
  "name": "click",
  "arguments": {
    "coordinate": "100,200"
  }
}

4. type_text

テキスト内容を入力します。

{
  "name": "type_text",
  "arguments": {
    "text": "Hello World"
  }
}

5. scroll_down / scroll_up

ページをスクロールします。

{
  "name": "scroll_down",
  "arguments": {}
}

6. hover

指定された位置にマウスをホバーさせます。

{
  "name": "hover",
  "arguments": {
    "coordinate": "100,200"
  }
}

7. resize_browser

ブラウザウィンドウのサイズを変更します。

{
  "name": "resize_browser",
  "arguments": {
    "size": "1200,800"
  }
}

8. get_page_content

現在のページのHTML内容を取得します。

{
  "name": "get_page_content",
  "arguments": {}
}

9. close_browser

ブラウザの接続を閉じます。

{
  "name": "close_browser",
  "arguments": {}
}

典型的なユースケース

1. ソーシャルメディアの自動化

# まずChromeでTwitter/Weiboに手動でログインする
# その後、MCPツールを使用して自動化する
launch_browser -> navigate_to -> click -> type_text

2. 電子商取引の操作

# 淘宝/京东のログイン状態を維持する
# 商品検索、価格監視などを自動化する
launch_browser -> navigate_to -> type_text -> click

3. データスクレイピング

# ログインが必要なウェブサイトからデータをスクレイピングする
# ログイン認証をバイパスし、直接操作する
launch_browser -> navigate_to -> get_page_content

🔧 技術詳細

高度な機能

インテリジェントなタブ管理

• 同じドメイン (例: example.com) のタブを再利用します。
• 異なるドメインの場合は自動的に新しいタブを作成します。
• 同じウェブサイトの重複した開き方を避けます。

自動待機メカニズム

• ネットワークアクティビティを監視し、ページの完全な読み込みを待機します。
• HTMLコンテンツの安定性を検出します。
• 動的コンテンツの読み込みを自動的に処理します。

エラー回復

• 接続が切断された場合、自動的に再接続します。
• 成功した接続エンドポイントをキャッシュします。
• 詳細なエラーログとフィードバックを提供します。

Docker環境のサポート

ChromeがDockerコンテナで実行されている場合:

# DockerでChromeを起動
docker run -d --name chrome-debug \
  -p 9222:9222 \
  --shm-size=2gb \
  zenika/alpine-chrome \
  --no-sandbox \
  --disable-dev-shm-usage \
  --remote-debugging-address=0.0.0.0 \
  --remote-debugging-port=9222

サーバーはDocker環境のChromeインスタンスを自動的に検出します。

トラブルシューティング

Chrome接続失敗

1. Chromeが--remote-debugging-port=9222で起動されていることを確認します。
2. ポート9222が占有されていないことを確認します: lsof -i :9222
3. 他のChromeインスタンスが実行されていないことを確認します。

操作タイムアウト

1. ネットワーク接続を確認します。
2. ページの読み込みタイムアウトを増やします。
3. ターゲットウェブサイトにアクセス可能であることを確認します。

スクリーンショット失敗

1. ページが完全に読み込まれていることを確認します。
2. ブラウザウィンドウのサイズ設定を確認します。
3. ページを更新して操作を再試行してみます。

技術アーキテクチャ

MCP Client ←→ stdio ←→ MCP Server ←→ Chrome Debug Port ←→ Chrome Browser

• トランスポートプロトコル: stdio (標準入出力)
• ブラウザエンジン: Puppeteer + Chrome DevTools Protocol
• 接続方法: WebSocket (Chromeデバッグポート)
• 画像形式: WebP/PNG base64エンコーディング

開発とデバッグ

# ウォッチモードでのコンパイル
npm run dev

# MCP通信ログを表示
DEBUG=mcp* npm start

npmへの公開

# プロジェクトをビルド
npm run build

# npmに公開
npm publish

謝辞

このプロジェクトの設計哲学とコアコンセプトは、RooCode プロジェクトに触発されています。RooCodeは優れたブラウザ自動化MCPサーバーの実装であり、貴重な技術的な参考と設計の洞察を提供してくれました。

RooCodeチームが以下の分野で貢献してくれたことに特別な感謝を表します。

• 🎯 MCPプロトコルの統合: MCPサーバーとブラウザ自動化を組み合わせるための技術的な解決策を提供しました。
• 🔗 ブラウザ接続: エレガントなブラウザ接続とセッション管理を実証しました。
• 📋 ツールAPI設計: 標準化されたブラウザ操作のための参照フレームワークを提供しました。

RooCodeの基盤の上に、このプロジェクトはさらに持続的なログインセッションを伴うブラウザ自動化に焦点を当て、既存のChromeデバッグポートに接続してユーザーセッションを維持することで、より実用的な自動化機能を実現しています。

📄 ライセンス

MIT License

主な利点: このMCPサーバーの最大の特徴は、既存のChromeインスタンスに接続し、ログインセッションを維持できることです。これにより、ユーザー認証が必要な自動化シナリオに最適です。Chromeのデバッグポートを通じて、ユーザーがログインしたブラウザセッションを引き継ぎ、真の「セッション持続型」のブラウザ自動化を実現します。