Content
# 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)
