Blueprint MCP Server

官方

通过MCP实现Chrome和Firefox的浏览器自动化

GitHub

文档

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 驱动的 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"]
    }
  }
}

快速开始

启动你的 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_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]，而不是提交公开问题。

致谢

此项目最初受微软 Playwright MCP 实现的启发，但已完全重写，使用基于浏览器扩展的自动化而非 Playwright。架构、实现和方法有根本不同。

主要区别：

使用带有 DevTools 协议的浏览器扩展（而非 Playwright）
使用真实浏览器配置文件（而非隔离上下文）
基于 WebSocket 的通信（而非 CDP 中继）
云中继选项用于远程访问
免费版和专业版模式
多浏览器支持（Chrome、Firefox、Edge、Opera）

我们感谢 Playwright 团队通过 MCP 开创了浏览器自动化。

许可证

Apache License 2.0 - 请参阅 LICENSE

由 Rails Blueprint 用 ❤️ 构建

网站 • GitHub • NPM