Blueprint MCP

Control your real browser with AI through the Model Context Protocol

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

npm install -g @railsblueprint/blueprint-mcp

2. Install the Browser Extension

Choose your browser:

Chrome / Edge / Opera

Chrome Web Store (works for all Chromium browsers)
Manual: Download from Releases, then load unpacked at chrome://extensions/ (Chrome), edge://extensions/ (Edge), or opera://extensions/ (Opera)

Firefox

Firefox Add-ons
Manual: Download from 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"]
    }
  }
}

Quick Start

Start your MCP client (Claude Desktop, Cursor, etc.)
Click the Blueprint MCP extension icon in your browser
The extension auto-connects to the MCP server
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

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

# 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

cd server
node cli.js --debug

Terminal 2: Build Chrome extension

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):

Open chrome://extensions/ (Chrome), edge://extensions/ (Edge), or opera://extensions/ (Opera)
Enable "Developer mode"
Click "Load unpacked"
Select the extensions/chrome/dist folder

For Firefox:

Open about:debugging#/runtime/this-firefox
Click "Load Temporary Add-on"
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

# Run tests
npm test

# Run with coverage
npm run test:coverage

Documentation:

Manual Test Procedures - Comprehensive manual testing guide
Feature Specification - Complete feature documentation
Test Progress - 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:

# 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

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

Check the extension is installed and enabled
Click the extension icon - it should show "Connected"
Check the MCP server is running (look for process on port 5555)
Try reloading the extension

"Port 5555 already in use"

Another instance is running. You can either:

Kill the existing process:

lsof -ti:5555 | xargs kill -9

Use a different port:

blueprint-mcp --port 8080

Browser tools not working

Make sure you've called enable first
Check you've attached to a tab with browser_tabs
Verify the tab still exists (wasn't closed)

Getting help

Contributing

We welcome contributions! See 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

Built with ❤️ by Rails Blueprint

Website • GitHub • NPM

Name		Name	Last commit message	Last commit date
Latest commit History 211 Commits
.beads		.beads
.github		.github
deprecated-packages/chrome-mcp		deprecated-packages/chrome-mcp
docs		docs
extensions		extensions
logs		logs
releases		releases
server		server
tmp		tmp
.gitignore		.gitignore
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
FEATURES.md		FEATURES.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
release.sh		release.sh

Folders and files

Latest commit

History

Repository files navigation

Blueprint MCP

What is this?

Why use this instead of Playwright/Puppeteer?

Installation

1. Install the MCP Server

2. Install the Browser Extension

3. Configure your MCP client

Quick Start

How it works

Free vs PRO

Free Tier (Default)

PRO Tier

Available Tools

Connection Management

Tab Management

Navigation

Content & Inspection

Interaction

Advanced

Extension Management

Development

Prerequisites

Setup

Running in Development

Project Structure

Testing

Configuration

Environment Variables

Command Line Options

Troubleshooting

Extension won't connect

"Port 5555 already in use"

Browser tools not working

Getting help

Contributing

Security

Credits

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 10

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages