blueprint-mcp
MCP server for browser automation across Chrome, Firefox, and Safari using real browser profiles
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/railsblueprint--blueprint-mcp)HTML
<a href="/listings/railsblueprint--blueprint-mcp"><img src="/api/listings/railsblueprint--blueprint-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Install the MCP Server
npm install -g @railsblueprint/blueprint-mcp
2. Install the Browser Extension
Choose your browser:
**Chrome / Edge / Opera** - [Chrome Web Store](https://chromewebstore.google.com/detail/blueprint-mcp-for-chrome/kpfkpbkijebomacngfgljaendniocdfp) (works for all Chromium browsers) - Manual: Download from [Releases](https://github.com/railsblueprint/blueprint-mcp/releases), then load unpacked at `chrome://extensions/` (Chrome), `edge://extensions/` (Edge), or `opera://extensions/` (Opera)
**Firefox** - [Firefox Add-ons](https://addons.mozilla.org/addon/blueprint-mcp-for-firefox/) - Manual: Download from [Releases](https://github.com/railsblueprint/blueprint-mcp/releases), then load at `about:debugging#/runtime/this-firefox`
3. Configure your MCP client
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["@railsblueprint/blueprint-mcp@latest"]
}
}
}**Claude Code** (AI-powered 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"]
}
}
}What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 414 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Blueprint MCP
- > Control your real browser with AI through the Model Context Protocol
- [](https://www.npmjs.com/package/@railsblueprint/blueprint-mcp)
- [](https://opensource.org/licenses/Apache-2.0)
- ## What is this?
- An MCP (Model Context Protocol) server that lets AI assistants control your actual browser (Chrome, Firefox, or Opera) through a browser extension. Unlike headless automation tools, this uses your real browser profile with all your logged-in sessions, cookies, and extensions intact.
- **Perfect for:** AI agents that need to interact with sites where you're already logged in, or that need to avoid bot detection.
- ## Why use this instead of Playwright/Puppeteer?
- | Blueprint MCP | Playwright/Puppeteer |
- |-------------------------|---------------------|
- | ✅ Real browser (not headless) | ❌ Headless or new browser instance |
- | ✅ Stays logged in to all your sites | ❌ Must re-authenticate each session |
- | ✅ Avoids bot detection (uses real fingerprint) | ⚠️ Often detected as automated browser |
- | ✅ Works with your existing browser extensions | ❌ No extension support |
- | ✅ Zero setup - works out of the box | ⚠️ Requires browser installation |
- | ✅ Chrome, Firefox, Edge, Opera support | ✅ Chrome, Firefox, Safari support |
- ## Installation
- ### 1. Install the MCP Server
- ```bash
- npm install -g @railsblueprint/blueprint-mcp
- ```
- ### 2. Install the Browser Extension
- Choose your browser:
- **Chrome / Edge / Opera**
- - [Chrome Web Store](https://chromewebstore.google.com/detail/blueprint-mcp-for-chrome/kpfkpbkijebomacngfgljaendniocdfp) (works for all Chromium browsers)
- - Manual: Download from [Releases](https://github.com/railsblueprint/blueprint-mcp/releases), then load unpacked at `chrome://extensions/` (Chrome), `edge://extensions/` (Edge), or `opera://extensions/` (Opera)
- **Firefox**
- - [Firefox Add-ons](https://addons.mozilla.org/addon/blueprint-mcp-for-firefox/)
- - Manual: Download from [Releases](https://github.com/railsblueprint/blueprint-mcp/releases), then load at `about:debugging#/runtime/this-firefox`
- ### 3. Configure your MCP client
- **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
- ```json
- {
- "mcpServers": {
- "browser": {
- "command": "npx",
- "args": ["@railsblueprint/blueprint-mcp@latest"]
- }
- }
- }
- ```
- **Claude Code** (AI-powered CLI):
- ```bash
- claude mcp add browser npx @railsblueprint/blueprint-mcp@latest
- ```
- **VS Code / Cursor** (`.vscode/settings.json`):
- ```json
- {
- "mcp.servers": {
- "browser": {
- "command": "npx",
- "args": ["@railsblueprint/blueprint-mcp@latest"]
- }
- }
- }
- ```
- ## Quick Start
- 1. **Start your MCP client** (Claude Desktop, Cursor, etc.)
- 2. **Click the Blueprint MCP extension icon** in your browser
- 3. The extension auto-connects to the MCP server
- 4. **Ask your AI assistant to browse!**
- **Example conversations:**
- ```
- 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*
- ```
- ## How it works
- ```
- ┌─────────────────────────┐
- │ 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 Tier (Default)
- - ✅ Local WebSocket connection (port 5555)
- - ✅ Single browser instance
- - ✅ All browser automation features
- - ✅ No account required
- - ❌ Limited to same machine
- ### PRO Tier
- - ✅ **Cloud relay** - connect from anywhere
- - ✅ **Multiple browsers** - control multiple browser instances
- - ✅ **Shared access** - multiple AI clients can use same browser
- - ✅ **Auto-reconnect** - maintains connection through network changes
- - ✅ **Priority support**
- [Upgrade to PRO](https://blueprint-mcp.railsblueprint.com)
- ## Available Tools
- The MCP server provides these tools to AI assistants:
- ### Connection Management
- - `enable` - Activate browser automation (required first step)
- - `disable` - Deactivate browser automation
- - `status` - Check connection status
- - `auth` - Login to PRO account (for cloud relay features)
- ### Tab Management
- - `browser_tabs` - List, create, attach to, or close browser tabs
- ### Navigation
- - `browser_navigate` - Navigate to a URL
- - `browser_navigate_back` - Go back in history
- ### Content & Inspection
- - `browser_snapshot` - Get accessible page content (recommended for reading pages)
- - `browser_take_screenshot` - Capture visual screenshot
- - `browser_console_messages` - Get browser console logs
- - `browser_network_requests` - Powerful network monitoring and replay tool with multiple actions:
- - **List mode** (default): Lightweight overview with filtering and pagination (default: 20 requests)
- - Filters: `urlPattern` (substring), `method` (GET/POST), `status` (200/404), `resourceType` (xhr/fetch/script)
- - Pagination: `limit` (default: 20), `offset` (default: 0)
- - Example: `action='list', urlPattern='api/users', method='GET', limit=10`
- - **Details mode**: Full request/response data for specific request including headers and bodies
- - **JSONPath filtering**: Query large JSON responses using JSONPath syntax (e.g., `$.data.items[0]`)
- - **Replay mode**: Re-execute captured requests with original headers and authentication
- - **Clear mode**: Clear captured history to free memory
- - Example: `action='details', requestId='12345.67', jsonPath='$.data.users[0]'`
- - `browser_extract_content` - Extract page content as markdown
- ### Interaction
- - `browser_interact` - Perform multiple actions in sequence (click, type, hover, wait, etc.)
- - `browser_click` - Click on elements
- - `browser_type` - Type text into inputs
- - `browser_hover` - Hover over elements
- - `browser_select_option` - Select dropdown options
- - `browser_fill_form` - Fill multiple form fields at once
- - `browser_press_key` - Press keyboard keys
- - `browser_drag` - Drag and drop elements
- ### Advanced
- - `browser_evaluate` - Execute JavaScript in page context
- - `browser_handle_dialog` - Handle alert/confirm/prompt dialogs
- - `browser_file_upload` - Upload files through file inputs
- - `browser_window` - Resize, minimize, maximize browser window
- - `browser_pdf_save` - Save current page as PDF
- - `browser_performance_metrics` - Get performance metrics
- - `browser_verify_text_visible` - Verify text is present (for testing)
- - `browser_verify_element_visible` - Verify element exists (for testing)
- ### Extension Management
- - `browser_list_extensions` - List installed browser extensions
- - `browser_reload_extensions` - Reload unpacked extensions (useful during development)
- ## Development
- ### Prerequisites
- - Node.js 18+
- - A supported browser (Chrome, Firefox, Edge, or Opera)
- - npm or yarn
- ### Setup
- ```bash
- # 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 ../..
- ```
- ### Running in Development
- **Terminal 1: Start MCP server in debug mode**
- ```bash
- cd server
- node cli.js --debug
- ```
- **Terminal 2: Build Chrome extension**
- ```bash
- cd extensions/chrome
- npm run build
- # or for watch mode:
- npm run dev
- ```
- **Note:** Firefox extension doesn't require a build step - it uses vanilla JavaScript and can be loaded directly from `extensions/firefox/`
- **Load extension in your browser:**
- For Chromium browsers (Chrome, Edge, Opera):
- 1. Open `chrome://extensions/` (Chrome), `edge://extensions/` (Edge), or `opera://extensions/` (Opera)
- 2. Enable "Developer mode"
- 3. Click "Load unpacked"
- 4. Select the `extensions/chrome/dist` folder
- For Firefox:
- 1. Open `about:debugging#/runtime/this-firefox`
- 2. Click "Load Temporary Add-on"
- 3. Select any file from the `extensions/firefox` folder
- ### Project Structure
- ```
- 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/
- ```
- ### Testing
- ```bash
- # Run tests
- npm test
- # Run with coverage
- npm run test:coverage
- ```
- **Documentation:**
- - [Manual Test Procedures](docs/testing/MANUAL_TEST_PROCEDURES.md) - Comprehensive manual testing guide
- - [Feature Specification](docs/testing/FEATURE_SPEC.md) - Complete feature documentation
- - [Test Progress](docs/testing/TEST_PROGRESS.md) - Current test coverage status
- ## Configuration
- The server works out-of-the-box with sensible defaults. For advanced configuration:
- ### Environment Variables
- Create a `.env` file in the project root:
- ```bash
- # Authentication server (PRO features)
- AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com
- # Local WebSocket port (Free tier)
- MCP_PORT=5555
- # Debug mode
- DEBUG=false
- ```
- ### Command Line Options
- ```bash
- blueprint-mcp --debug # Enable verbose logging
- blueprint-mcp --port 8080 # Use custom WebSocket port (default: 5555)
- blueprint-mcp --debug --port 8080 # Combine options
- ```
- **Note:** If you change the port, you'll need to update your browser extension settings to match.
- ## Troubleshooting
- ### Extension won't connect
- 1. Check the extension is installed and enabled
- 2. Click the extension icon - it should show "Connected"
- 3. Check the MCP server is running (look for process on port 5555)
- 4. Try reloading the extension
- ### "Port 5555 already in use"
- Another instance is running. You can either:
- 1. Kill the existing process:
- ```bash
- lsof -ti:5555 | xargs kill -9
- ```
- 2. Use a different port:
- ```bash
- blueprint-mcp --port 8080
- ```
- ### Browser tools not working
- 1. Make sure you've called `enable` first
- 2. Check you've attached to a tab with `browser_tabs`
- 3. Verify the tab still exists (wasn't closed)
- ### Getting help
- - [GitHub Issues](https://github.com/railsblueprint/blueprint-mcp/issues)
- - [Documentation](https://blueprint-mcp.railsblueprint.com/docs)
- ## Contributing
- We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
- ## Security
- This tool gives AI assistants control over your browser. Please review:
- - The MCP server only accepts local connections by default (localhost:5555)
- - PRO relay connections are authenticated via OAuth
- - The extension requires explicit user action to connect
- - All browser actions go through the browser's permission system
- Found a security issue? Please email security@railsblueprint.com instead of filing a public issue.
- ## Credits
- This project was originally inspired by Microsoft's Playwright MCP implementation but has been completely rewritten to use browser extension-based automation instead of Playwright. The architecture, implementation, and approach are fundamentally different.
- **Key differences:**
- - Uses browser extensions with DevTools Protocol (not Playwright)
- - Works with real browser profiles (not isolated contexts)
- - WebSocket-based communication (not CDP relay)
- - Cloud relay option for remote access
- - Free and PRO tier model
- - Multi-browser support (Chrome, Firefox, Edge, Opera)
- We're grateful to the Playwright team for pioneering browser automation via MCP.
- ## License
- Apache License 2.0 - see [LICENSE](LICENSE)
- Copyright (c) 2025 Rails Blueprint
- ---
- **Built with ❤️ by [Rails Blueprint](https://railsblueprint.com)**
- [Website](https://blueprint-mcp.railsblueprint.com) •
- [GitHub](https://github.com/railsblueprint/blueprint-mcp) •
- [NPM](https://www.npmjs.com/package/@railsblueprint/blueprint-mcp)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.