Blueprint MCP Server

官方

透過 MCP 進行 Chrome 與 Firefox 的瀏覽器自動化

文件

Blueprint MCP

透過模型上下文協定，讓 AI 控制你真實的瀏覽器

這是什麼？

一個 MCP（模型上下文協定）伺服器，讓 AI 助理能透過瀏覽器擴充功能，控制你真實的瀏覽器（Chrome、Firefox 或 Opera）。與無頭自動化工具不同，它使用你真實的瀏覽器設定檔，保留所有已登入的會話、Cookie 和擴充功能。

非常適合： 需要與你已登入的網站互動，或需要避免機器人偵測的 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 驅動的命令列介面）：

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

快速入門

啟動你的 MCP 客戶端（Claude Desktop、Cursor 等）
點擊瀏覽器中的 Blueprint MCP 擴充功能圖示
擴充功能會自動連接到 MCP 伺服器
要求你的 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)        │
└─────────────────────────┘

免費版 vs 專業版

免費版（預設）

✅ 本機 WebSocket 連線（連接埠 5555）
✅ 單一瀏覽器實例
✅ 所有瀏覽器自動化功能
✅ 無需帳號
❌ 僅限同一台機器

專業版

✅ 雲端中繼 - 從任何地方連線
✅ 多瀏覽器 - 控制多個瀏覽器實例
✅ 共享存取 - 多個 AI 客戶端可使用同一個瀏覽器
✅ 自動重新連線 - 在網路變更時維持連線
✅ 優先支援

升級到專業版

可用工具

MCP 伺服器提供以下工具給 AI 助理：

連線管理

enable - 啟用瀏覽器自動化（必要的第一步）
disable - 停用瀏覽器自動化
status - 檢查連線狀態
auth - 登入專業版帳號（用於雲端中繼功能）

分頁管理

browser_tabs - 列出、建立、附加或關閉瀏覽器分頁

導覽

browser_navigate - 導覽到某個網址
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 - 處理 alert/confirm/prompt 對話框
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）：

開啟 chrome://extensions/（Chrome）、edge://extensions/（Edge）或 opera://extensions/（Opera）
啟用「開發人員模式」
點擊「載入未封裝項目」
選取 extensions/chrome/dist 資料夾

對於 Firefox：

開啟 about:debugging#/runtime/this-firefox
點擊「載入暫時附加元件」
從 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

注意： 如果你變更了連接埠，你需要更新瀏覽器擴充功能設定以符合。

疑難排解

擴充功能無法連線

檢查擴充功能是否已安裝並啟用
點擊擴充功能圖示 - 應顯示「已連線」
檢查 MCP 伺服器是否正在執行（尋找連接埠 5555 的程序）
嘗試重新載入擴充功能

「連接埠 5555 已被使用」

另一個實例正在執行。你可以：

終止現有程序：

lsof -ti:5555 | xargs kill -9

使用不同的連接埠：

blueprint-mcp --port 8080

瀏覽器工具無法運作

確保你已先呼叫 enable
檢查你是否已使用 browser_tabs 附加到分頁
驗證該分頁仍然存在（未被關閉）

取得協助

貢獻

我們歡迎貢獻！請參閱 CONTRIBUTING.md 了解指南。

安全性

此工具讓 AI 助理控制你的瀏覽器。請審閱：

MCP 伺服器預設僅接受本機連線（localhost:5555）
專業版中繼連線透過 OAuth 驗證
擴充功能需要明確的使用者操作才能連線
所有瀏覽器操作都經過瀏覽器的權限系統

發現安全問題？請發送郵件至 [email protected]，而不是提交公開議題。

致謝

此專案最初受到 Microsoft 的 Playwright MCP 實作啟發，但已完全重寫為使用基於瀏覽器擴充功能的自動化，而非 Playwright。架構、實作和方法有根本上的不同。

主要差異：

使用具備 DevTools Protocol 的瀏覽器擴充功能（而非 Playwright）
使用真實的瀏覽器設定檔（而非隔離的上下文）
基於 WebSocket 的通訊（而非 CDP 中繼）
用於遠端存取的雲端中繼選項
免費版與專業版模式
多瀏覽器支援（Chrome、Firefox、Edge、Opera）

我們感謝 Playwright 團隊開創了透過 MCP 進行瀏覽器自動化的先河。

授權

Apache License 2.0 - 請參閱 LICENSE

由 Rails Blueprint 用 ❤️ 打造

網站 • GitHub • NPM