Blueprint Mcp For Chrome

Blueprint MCP

Model Context Protocol を通じて、AI で実際のブラウザーを操作します

これは何ですか？

ブラウザー拡張機能を通じて、AI アシスタントが実際のブラウザー（Chrome、Firefox、Opera）を操作できるようにする MCP（Model Context Protocol）サーバーです。ヘッドレス自動化ツールとは異なり、ログイン済みのセッション、Cookie、拡張機能をすべて保持したまま、実際のブラウザープロファイルを使用します。

最適な用途： すでにログインしているサイトを操作する必要があるAIエージェントや、ボット検出を回避する必要があるAIエージェント。

Playwright/Puppeteer ではなく、これを使う理由

Blueprint MCP	Playwright/Puppeteer
✅ 実際のブラウザー（ヘッドレスではありません）	❌ ヘッドレスまたは新しいブラウザーインスタンス
✅ すべてのサイトにログインした状態を維持	❌ セッションごとに再認証が必要
✅ ボット検出を回避（実際のフィンガープリントを使用）	⚠️ 自動化されたブラウザーとして検出されることがよくあります
✅ 既存のブラウザー拡張機能で動作	❌ 拡張機能をサポートしていません
✅ セットアップ不要ですぐに使えます	⚠️ ブラウザーのインストールが必要
✅ Chrome、Firefox、Edge、Opera をサポート	✅ Chrome、Firefox、Safari をサポート

インストール

1. MCP サーバーをインストールする

npm install -g @railsblueprint/blueprint-mcp

2. ブラウザー拡張機能をインストールする

ブラウザーを選択してください。

Chrome / Edge / Opera

• Chrome ウェブストア（すべての Chromium ブラウザーで動作します）
• 手動： Releases からダウンロードし、chrome://extensions/（Chrome）、edge://extensions/（Edge）、または opera://extensions/（Opera）で展開済みの拡張機能を読み込みます

Firefox

• Firefox アドオン
• 手動： Releases からダウンロードし、about:debugging#/runtime/this-firefox で読み込みます

3. MCP クライアントを設定する

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

Claude Code（AI 搭載の CLI）：

claude mcp add browser npx @railsblueprint/blueprint-mcp@latest

VS Code / Cursor（.vscode/settings.json）：

{
  "mcp.servers": {
    "browser": {
      "command": "npx",
      "args": ["@railsblueprint/blueprint-mcp@latest"]
    }
  }
}

クイックスタート

1. MCP クライアント（Claude Desktop、Cursor など）を起動します
2. ブラウザーで Blueprint MCP 拡張機能のアイコンをクリックします
3. 拡張機能が MCP サーバーに自動接続します
4. AI アシスタントにブラウジングを依頼します！

会話の例：

You: "Go to GitHub and check my notifications"
AI: *navigates to github.com, clicks notifications, reads content*

You: "Fill out this form with my info"
AI: *reads form fields, fills them in, submits*

You: "Take a screenshot of this page"
AI: *captures screenshot and shows you*

仕組み

┌─────────────────────────┐
│   AI Assistant          │
│   (Claude, GPT, etc)    │
└───────────┬─────────────┘
            │
            │ MCP Protocol
            ↓
┌─────────────────────────┐
│   MCP Client            │
│   (Claude Desktop, etc) │
└───────────┬─────────────┘
            │
            │ stdio/JSON-RPC
            ↓
┌─────────────────────────┐
│   blueprint-mcp         │
│   (this package)        │
└───────────┬─────────────┘
            │
            │ WebSocket (localhost:5555 or cloud relay)
            ↓
┌─────────────────────────┐
│   Browser Extension     │
└───────────┬─────────────┘
            │
            │ Browser Extension APIs
            ↓
┌─────────────────────────┐
│   Your Browser          │
│   (real profile)        │
└─────────────────────────┘

Free と PRO の比較

Free プラン（デフォルト）

• ✅ ローカル WebSocket 接続（ポート 5555）
• ✅ 単一のブラウザーインスタンス
• ✅ すべてのブラウザー自動化機能
• ✅ アカウント登録不要
• ❌ 同じマシン上でのみ利用可能

PRO プラン

• ✅ クラウドリレー - どこからでも接続
• ✅ 複数のブラウザー - 複数のブラウザーインスタンスを操作
• ✅ 共有アクセス - 複数の AI クライアントで同じブラウザーを利用
• ✅ 自動再接続 - ネットワークの変更中も接続を維持
• ✅ 優先サポート

PRO にアップグレード

利用可能なツール

MCP サーバーは、AI アシスタントに以下のツールを提供します。

接続管理

• enable - ブラウザー自動化を有効にします（最初に必要な手順）
• disable - ブラウザー自動化を無効にします
• status - 接続状態を確認します
• auth - PRO アカウントにログインします（クラウドリレー機能用）

タブ管理

• browser_tabs - ブラウザーのタブを一覧表示、新規作成、接続、または閉じます

ナビゲーション

• browser_navigate - URL に移動します
• browser_navigate_back - 履歴を戻ります

コンテンツと検査

• browser_snapshot - アクセス可能なページコンテンツを取得します（ページを読む場合に推奨）
• browser_take_screenshot - 画面のスクリーンショットを撮影します
• browser_console_messages - ブラウザーのコンソールログを取得します
• browser_network_requests - 複数のアクションに対応した強力なネットワーク監視・再生ツールです：
  • List mode（デフォルト）：フィルタリングとページネーションに対応した軽量な概要を表示します（デフォルト：20 件のリクエスト）
    • フィルター：urlPattern（部分一致）、method（GET/POST）、status（200/404）、resourceType（xhr/fetch/script）
    • ページネーション：limit（デフォルト：20）、offset（デフォルト：0）
    • 例：action='list', urlPattern='api/users', method='GET', limit=10
  • Details mode：指定したリクエストのヘッダーや本文を含む、完全なリクエスト／レスポンスデータを表示します
  • JSONPath filtering：JSONPath 構文を使って大きな JSON レスポンスをクエリします（例：$.data.items[0]）
  • Replay mode：元のヘッダーと認証情報を使って、キャプチャしたリクエストを再実行します
  • Clear mode：キャプチャした履歴を消去してメモリを解放します
  • 例：action='details', requestId='12345.67', jsonPath='$.data.users[0]'
• browser_extract_content - ページコンテンツを Markdown として抽出します

操作

• browser_interact - 複数のアクション（クリック、入力、ホバー、待機など）を順番に実行します
• browser_click - 要素をクリックします
• browser_type - 入力欄にテキストを入力します
• browser_hover - 要素にマウスカーソルを合わせます
• browser_select_option - ドロップダウンのオプションを選択します
• browser_fill_form - 複数のフォームフィールドに一度に入力します
• browser_press_key - キーを押します
• browser_drag - 要素をドラッグ＆ドロップします

高度な機能

• browser_evaluate - ページのコンテキストで JavaScript を実行します
• browser_handle_dialog - アラート／確認／プロンプトダイアログを処理します
• browser_file_upload - ファイル入力欄からファイルをアップロードします
• browser_window - ブラウザーウィンドウを拡大・縮小、最小化、最大化します
• browser_pdf_save - 現在のページを PDF として保存します
• browser_performance_metrics - パフォーマンス指標を取得します
• browser_verify_text_visible - テキストが存在することを確認します（テスト用）
• browser_verify_element_visible - 要素が存在することを確認します（テスト用）

拡張機能の管理

• browser_list_extensions - インストール済みのブラウザー拡張機能を一覧表示します
• browser_reload_extensions - 展開済みの拡張機能を再読み込みします（開発時に便利です）

開発

前提条件

• Node.js 18+
• 対応ブラウザー（Chrome、Firefox、Edge、Opera）
• npm または yarn

セットアップ

# Clone the repository
git clone https://github.com/railsblueprint/blueprint-mcp.git
cd blueprint-mcp

# Install server dependencies
cd server
npm install
cd ..

# Install Chrome extension dependencies
cd extensions/chrome
npm install
cd ../..

開発時の実行

ターミナル 1：MCP サーバーをデバッグモードで起動

cd server
node cli.js --debug

ターミナル 2：Chrome 拡張機能をビルド

cd extensions/chrome
npm run build
# or for watch mode:
npm run dev

注： Firefox 拡張機能ではビルド手順は不要です。標準の JavaScript を使用しているため、extensions/firefox/ から直接読み込めます。

ブラウザーに拡張機能を読み込む：

Chromium 系ブラウザー（Chrome、Edge、Opera）の場合：

1. chrome://extensions/（Chrome）、edge://extensions/（Edge）、または opera://extensions/（Opera）を開きます
2. 「デベロッパー モード」を有効にします
3. 「パッケージ化されていない拡張機能を読み込む」をクリックします
4. extensions/chrome/dist フォルダーを選択します

Firefox の場合：

1. about:debugging#/runtime/this-firefox を開きます
2. 「一時的なアドオンを読み込む」をクリックします
3. extensions/firefox フォルダー内の任意のファイルを選択します

プロジェクト構成

blueprint-mcp/
├── server/                     # MCP Server
│   ├── cli.js                  # Server entry point
│   ├── src/
│   │   ├── statefulBackend.js  # Connection state management
│   │   ├── unifiedBackend.js   # MCP tool implementations
│   │   ├── extensionServer.js  # WebSocket server for extension
│   │   ├── mcpConnection.js    # Proxy/relay connection handling
│   │   ├── transport.js        # Transport abstraction layer
│   │   ├── oauth.js            # OAuth2 client for PRO features
│   │   └── fileLogger.js       # Debug logging
│   └── tests/                  # Server test suites
├── extensions/                 # Browser Extensions
│   ├── chrome/                 # Chrome extension (TypeScript + Vite)
│   │   └── src/
│   │       ├── background.ts   # Extension service worker
│   │       ├── content-script.ts # Page content injection
│   │       └── utils/          # Utility functions
│   ├── firefox/                # Firefox extension (Vanilla JS)
│   │   └── src/
│   │       ├── background.js   # Service worker
│   │       └── content-script.js # Page injection
│   ├── shared/                 # Shared code between extensions
│   └── build-*.js              # Build scripts for each browser
├── docs/                       # Documentation
│   ├── testing/                # Test documentation
│   ├── architecture/           # Architecture docs
│   └── stores/                 # Browser store assets
└── releases/                   # Built extensions for distribution
    ├── chrome/
    ├── firefox/
    ├── edge/
    └── opera/

テスト

# Run tests
npm test

# Run with coverage
npm run test:coverage

ドキュメント：

• 手動テスト手順 - 手動テストの包括的なガイド
• 機能仕様 - 機能の完全なドキュメント
• テストの進捗 - 現在のテストカバレッジ状況

設定

サーバーは適切なデフォルト設定ですぐに動作します。詳細な設定を行う場合：

環境変数

プロジェクトのルートに .env ファイルを作成します：

# Authentication server (PRO features)
AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com

# Local WebSocket port (Free tier)
MCP_PORT=5555

# Debug mode
DEBUG=false

コマンドラインオプション

blueprint-mcp --debug              # Enable verbose logging
blueprint-mcp --port 8080          # Use custom WebSocket port (default: 5555)
blueprint-mcp --debug --port 8080  # Combine options

注： ポートを変更した場合は、ブラウザー拡張機能の設定も一致するように更新する必要があります。

トラブルシューティング

拡張機能が接続されない場合

1. 拡張機能がインストールされ、有効になっていることを確認してください
2. 拡張機能のアイコンをクリックしてください。「接続済み」と表示されるはずです
3. MCP サーバーが実行中であることを確認してください（ポート 5555 のプロセスを確認します）
4. 拡張機能を再読み込みしてみてください

「ポート 5555 はすでに使用されています」

別のインスタンスが実行中です。次のいずれかを行ってください。

1. 既存のプロセスを終了します。

lsof -ti:5555 | xargs kill -9

2. 別のポートを使用します。

blueprint-mcp --port 8080

ブラウザツールが動作しない場合

1. 最初に enable を呼び出したことを確認してください
2. browser_tabs を使ってタブに接続したことを確認してください
3. タブがまだ存在すること（閉じられていないこと）を確認してください

サポート

• GitHub のイシュー
• ドキュメント

コントリビューション

コントリビューションを歓迎します！ガイドラインについてはCONTRIBUTING.mdをご覧ください。

セキュリティ

このツールを使うと、AI アシスタントがブラウザを操作できます。以下をご確認ください。

• MCP サーバーは、デフォルトでローカル接続（localhost:5555）のみを受け付けます
• PRO のリレー接続は OAuth で認証されます
• 接続するには、ユーザーによる明示的な操作が必要です
• すべてのブラウザ操作は、ブラウザの権限システムを経由します

セキュリティ上の問題を発見した場合は、公開イシューを作成せず、[email protected] にメールでご連絡ください。

クレジット

このプロジェクトは、もともと Microsoft の Playwright MCP 実装に着想を得ていますが、Playwright の代わりにブラウザ拡張機能ベースの自動化を使用するよう、全面的に書き直されています。アーキテクチャ、実装、アプローチは根本的に異なります。

主な違い：

• Playwright ではなく、DevTools Protocol を使用するブラウザ拡張機能を使用します
• 分離されたコンテキストではなく、実際のブラウザプロファイルで動作します
• CDP リレーではなく、WebSocket ベースの通信を使用します
• リモートアクセス用のクラウドリレーオプションがあります
• Free および PRO の料金プランがあります
• 複数のブラウザに対応しています（Chrome、Firefox、Edge、Opera）

MCP を介したブラウザ自動化を先駆けて実現した Playwright チームに感謝します。

ライセンス

Apache License 2.0。詳細は LICENSE をご覧ください。

Copyright (c) 2025 Rails Blueprint

---

Rails Blueprint が ❤️ を込めて開発

ウェブサイト • GitHub • NPM