Blueprint MCP Server

公式

Chrome および Firefox 向けの MCP によるブラウザ自動化

GitHub
85

ドキュメント

Blueprint MCP

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

npm version License

これは何ですか？

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

最適な用途: 既にログインしているサイトとやり取りする必要がある、またはボット検出を回避する必要があるAIエージェント。

Playwright/Puppeteerの代わりにこれを使用する理由

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

インストール

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

npm install -g @railsblueprint/blueprint-mcp

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

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

Chrome / Edge / Opera

  • Chrome Web Store (すべてのChromiumブラウザで動作)
  • 手動: Releasesからダウンロードし、chrome://extensions/ (Chrome)、edge://extensions/ (Edge)、またはopera://extensions/ (Opera)でパッケージ化されていない拡張機能を読み込む

Firefox

  • Firefox Add-ons
  • 手動: 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 vs 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 - 複数のアクションを持つ強力なネットワーク監視および再生ツール:
    • リストモード (デフォルト): フィルタリングとページネーション付きの軽量概要（デフォルト: 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
    • 詳細モード: ヘッダーとボディを含む特定のリクエストの完全なリクエスト/レスポンスデータ
    • JSONPathフィルタリング: JSONPath構文を使用して大きなJSONレスポンスをクエリ（例: $.data.items[0]）
    • 再生モード: 元のヘッダーと認証情報でキャプチャされたリクエストを再実行
    • クリアモード: キャプチャ履歴をクリアしてメモリを解放
    • 例: 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. 拡張機能アイコンをクリック - 「Connected」と表示されるはずです
  3. MCPサーバーが実行中か確認する（ポート5555のプロセスを探す）
  4. 拡張機能をリロードしてみる

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

別のインスタンスが実行中です。以下のいずれかを実行できます:

  1. 既存のプロセスを終了:
lsof -ti:5555 | xargs kill -9
  1. 別のポートを使用:
blueprint-mcp --port 8080

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

  1. 最初にenableを呼び出したか確認する
  2. browser_tabsでタブにアタッチしたか確認する
  3. タブがまだ存在するか確認する（閉じられていないか）

ヘルプを得る

貢献

貢献を歓迎します！ガイドラインはCONTRIBUTING.mdを参照してください。

セキュリティ

このツールはAIアシスタントにブラウザの制御を許可します。以下を確認してください:

  • MCPサーバーはデフォルトでローカル接続のみ受け付けます（localhost:5555）
  • PROリレー接続はOAuthで認証されます
  • 拡張機能は接続に明示的なユーザーアクションを必要とします
  • すべてのブラウザアクションはブラウザの権限システムを通過します

セキュリティ問題を発見した場合は、公開Issueを提出する代わりに[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が作成

Webサイト • GitHub • NPM