Chrome Debug MCP

🚀 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 Web Storeの承認も不要です。
• 📱 インテリジェントなタブ管理: 同じドメインのタブを再利用し、重複した開き方を避けます。
• 🖼️ リアルタイムスクリーンショットフィードバック: 各操作後に自動的にスクリーンショットを撮り、視覚的なフィードバックを提供します。
• 🌐 ネットワークアクティビティ監視: ページの読み込み完了を自動的に待ちます。
• 🐳 ネイティブ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ライセンス

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