Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/railsblueprint--blueprint-mcp/badge.svg)](/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

i

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)

  1. # Blueprint MCP
  2. > Control your real browser with AI through the Model Context Protocol
  3. [![npm version](https://badge.fury.io/js/@railsblueprint%2Fblueprint-mcp.svg)](https://www.npmjs.com/package/@railsblueprint/blueprint-mcp)
  4. [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  5. ## What is this?
  6. 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.
  7. **Perfect for:** AI agents that need to interact with sites where you're already logged in, or that need to avoid bot detection.
  8. ## Why use this instead of Playwright/Puppeteer?
  9. | Blueprint MCP | Playwright/Puppeteer |
  10. |-------------------------|---------------------|
  11. | ✅ Real browser (not headless) | ❌ Headless or new browser instance |
  12. | ✅ Stays logged in to all your sites | ❌ Must re-authenticate each session |
  13. | ✅ Avoids bot detection (uses real fingerprint) | ⚠️ Often detected as automated browser |
  14. | ✅ Works with your existing browser extensions | ❌ No extension support |
  15. | ✅ Zero setup - works out of the box | ⚠️ Requires browser installation |
  16. | ✅ Chrome, Firefox, Edge, Opera support | ✅ Chrome, Firefox, Safari support |
  17. ## Installation
  18. ### 1. Install the MCP Server
  19. ```bash
  20. npm install -g @railsblueprint/blueprint-mcp
  21. ```
  22. ### 2. Install the Browser Extension
  23. Choose your browser:
  24. **Chrome / Edge / Opera**
  25. - [Chrome Web Store](https://chromewebstore.google.com/detail/blueprint-mcp-for-chrome/kpfkpbkijebomacngfgljaendniocdfp) (works for all Chromium browsers)
  26. - 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)
  27. **Firefox**
  28. - [Firefox Add-ons](https://addons.mozilla.org/addon/blueprint-mcp-for-firefox/)
  29. - Manual: Download from [Releases](https://github.com/railsblueprint/blueprint-mcp/releases), then load at `about:debugging#/runtime/this-firefox`
  30. ### 3. Configure your MCP client
  31. **Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
  32. ```json
  33. {
  34. "mcpServers": {
  35. "browser": {
  36. "command": "npx",
  37. "args": ["@railsblueprint/blueprint-mcp@latest"]
  38. }
  39. }
  40. }
  41. ```
  42. **Claude Code** (AI-powered CLI):
  43. ```bash
  44. claude mcp add browser npx @railsblueprint/blueprint-mcp@latest
  45. ```
  46. **VS Code / Cursor** (`.vscode/settings.json`):
  47. ```json
  48. {
  49. "mcp.servers": {
  50. "browser": {
  51. "command": "npx",
  52. "args": ["@railsblueprint/blueprint-mcp@latest"]
  53. }
  54. }
  55. }
  56. ```
  57. ## Quick Start
  58. 1. **Start your MCP client** (Claude Desktop, Cursor, etc.)
  59. 2. **Click the Blueprint MCP extension icon** in your browser
  60. 3. The extension auto-connects to the MCP server
  61. 4. **Ask your AI assistant to browse!**
  62. **Example conversations:**
  63. ```
  64. You: "Go to GitHub and check my notifications"
  65. AI: *navigates to github.com, clicks notifications, reads content*
  66. You: "Fill out this form with my info"
  67. AI: *reads form fields, fills them in, submits*
  68. You: "Take a screenshot of this page"
  69. AI: *captures screenshot and shows you*
  70. ```
  71. ## How it works
  72. ```
  73. ┌─────────────────────────┐
  74. │ AI Assistant │
  75. │ (Claude, GPT, etc) │
  76. └───────────┬─────────────┘
  77. │
  78. │ MCP Protocol
  79. ↓
  80. ┌─────────────────────────┐
  81. │ MCP Client │
  82. │ (Claude Desktop, etc) │
  83. └───────────┬─────────────┘
  84. │
  85. │ stdio/JSON-RPC
  86. ↓
  87. ┌─────────────────────────┐
  88. │ blueprint-mcp │
  89. │ (this package) │
  90. └───────────┬─────────────┘
  91. │
  92. │ WebSocket (localhost:5555 or cloud relay)
  93. ↓
  94. ┌─────────────────────────┐
  95. │ Browser Extension │
  96. └───────────┬─────────────┘
  97. │
  98. │ Browser Extension APIs
  99. ↓
  100. ┌─────────────────────────┐
  101. │ Your Browser │
  102. │ (real profile) │
  103. └─────────────────────────┘
  104. ```
  105. ## Free vs PRO
  106. ### Free Tier (Default)
  107. - ✅ Local WebSocket connection (port 5555)
  108. - ✅ Single browser instance
  109. - ✅ All browser automation features
  110. - ✅ No account required
  111. - ❌ Limited to same machine
  112. ### PRO Tier
  113. - ✅ **Cloud relay** - connect from anywhere
  114. - ✅ **Multiple browsers** - control multiple browser instances
  115. - ✅ **Shared access** - multiple AI clients can use same browser
  116. - ✅ **Auto-reconnect** - maintains connection through network changes
  117. - ✅ **Priority support**
  118. [Upgrade to PRO](https://blueprint-mcp.railsblueprint.com)
  119. ## Available Tools
  120. The MCP server provides these tools to AI assistants:
  121. ### Connection Management
  122. - `enable` - Activate browser automation (required first step)
  123. - `disable` - Deactivate browser automation
  124. - `status` - Check connection status
  125. - `auth` - Login to PRO account (for cloud relay features)
  126. ### Tab Management
  127. - `browser_tabs` - List, create, attach to, or close browser tabs
  128. ### Navigation
  129. - `browser_navigate` - Navigate to a URL
  130. - `browser_navigate_back` - Go back in history
  131. ### Content & Inspection
  132. - `browser_snapshot` - Get accessible page content (recommended for reading pages)
  133. - `browser_take_screenshot` - Capture visual screenshot
  134. - `browser_console_messages` - Get browser console logs
  135. - `browser_network_requests` - Powerful network monitoring and replay tool with multiple actions:
  136. - **List mode** (default): Lightweight overview with filtering and pagination (default: 20 requests)
  137. - Filters: `urlPattern` (substring), `method` (GET/POST), `status` (200/404), `resourceType` (xhr/fetch/script)
  138. - Pagination: `limit` (default: 20), `offset` (default: 0)
  139. - Example: `action='list', urlPattern='api/users', method='GET', limit=10`
  140. - **Details mode**: Full request/response data for specific request including headers and bodies
  141. - **JSONPath filtering**: Query large JSON responses using JSONPath syntax (e.g., `$.data.items[0]`)
  142. - **Replay mode**: Re-execute captured requests with original headers and authentication
  143. - **Clear mode**: Clear captured history to free memory
  144. - Example: `action='details', requestId='12345.67', jsonPath='$.data.users[0]'`
  145. - `browser_extract_content` - Extract page content as markdown
  146. ### Interaction
  147. - `browser_interact` - Perform multiple actions in sequence (click, type, hover, wait, etc.)
  148. - `browser_click` - Click on elements
  149. - `browser_type` - Type text into inputs
  150. - `browser_hover` - Hover over elements
  151. - `browser_select_option` - Select dropdown options
  152. - `browser_fill_form` - Fill multiple form fields at once
  153. - `browser_press_key` - Press keyboard keys
  154. - `browser_drag` - Drag and drop elements
  155. ### Advanced
  156. - `browser_evaluate` - Execute JavaScript in page context
  157. - `browser_handle_dialog` - Handle alert/confirm/prompt dialogs
  158. - `browser_file_upload` - Upload files through file inputs
  159. - `browser_window` - Resize, minimize, maximize browser window
  160. - `browser_pdf_save` - Save current page as PDF
  161. - `browser_performance_metrics` - Get performance metrics
  162. - `browser_verify_text_visible` - Verify text is present (for testing)
  163. - `browser_verify_element_visible` - Verify element exists (for testing)
  164. ### Extension Management
  165. - `browser_list_extensions` - List installed browser extensions
  166. - `browser_reload_extensions` - Reload unpacked extensions (useful during development)
  167. ## Development
  168. ### Prerequisites
  169. - Node.js 18+
  170. - A supported browser (Chrome, Firefox, Edge, or Opera)
  171. - npm or yarn
  172. ### Setup
  173. ```bash
  174. # Clone the repository
  175. git clone https://github.com/railsblueprint/blueprint-mcp.git
  176. cd blueprint-mcp
  177. # Install server dependencies
  178. cd server
  179. npm install
  180. cd ..
  181. # Install Chrome extension dependencies
  182. cd extensions/chrome
  183. npm install
  184. cd ../..
  185. ```
  186. ### Running in Development
  187. **Terminal 1: Start MCP server in debug mode**
  188. ```bash
  189. cd server
  190. node cli.js --debug
  191. ```
  192. **Terminal 2: Build Chrome extension**
  193. ```bash
  194. cd extensions/chrome
  195. npm run build
  196. # or for watch mode:
  197. npm run dev
  198. ```
  199. **Note:** Firefox extension doesn't require a build step - it uses vanilla JavaScript and can be loaded directly from `extensions/firefox/`
  200. **Load extension in your browser:**
  201. For Chromium browsers (Chrome, Edge, Opera):
  202. 1. Open `chrome://extensions/` (Chrome), `edge://extensions/` (Edge), or `opera://extensions/` (Opera)
  203. 2. Enable "Developer mode"
  204. 3. Click "Load unpacked"
  205. 4. Select the `extensions/chrome/dist` folder
  206. For Firefox:
  207. 1. Open `about:debugging#/runtime/this-firefox`
  208. 2. Click "Load Temporary Add-on"
  209. 3. Select any file from the `extensions/firefox` folder
  210. ### Project Structure
  211. ```
  212. blueprint-mcp/
  213. ├── server/ # MCP Server
  214. │ ├── cli.js # Server entry point
  215. │ ├── src/
  216. │ │ ├── statefulBackend.js # Connection state management
  217. │ │ ├── unifiedBackend.js # MCP tool implementations
  218. │ │ ├── extensionServer.js # WebSocket server for extension
  219. │ │ ├── mcpConnection.js # Proxy/relay connection handling
  220. │ │ ├── transport.js # Transport abstraction layer
  221. │ │ ├── oauth.js # OAuth2 client for PRO features
  222. │ │ └── fileLogger.js # Debug logging
  223. │ └── tests/ # Server test suites
  224. ├── extensions/ # Browser Extensions
  225. │ ├── chrome/ # Chrome extension (TypeScript + Vite)
  226. │ │ └── src/
  227. │ │ ├── background.ts # Extension service worker
  228. │ │ ├── content-script.ts # Page content injection
  229. │ │ └── utils/ # Utility functions
  230. │ ├── firefox/ # Firefox extension (Vanilla JS)
  231. │ │ └── src/
  232. │ │ ├── background.js # Service worker
  233. │ │ └── content-script.js # Page injection
  234. │ ├── shared/ # Shared code between extensions
  235. │ └── build-*.js # Build scripts for each browser
  236. ├── docs/ # Documentation
  237. │ ├── testing/ # Test documentation
  238. │ ├── architecture/ # Architecture docs
  239. │ └── stores/ # Browser store assets
  240. └── releases/ # Built extensions for distribution
  241. ├── chrome/
  242. ├── firefox/
  243. ├── edge/
  244. └── opera/
  245. ```
  246. ### Testing
  247. ```bash
  248. # Run tests
  249. npm test
  250. # Run with coverage
  251. npm run test:coverage
  252. ```
  253. **Documentation:**
  254. - [Manual Test Procedures](docs/testing/MANUAL_TEST_PROCEDURES.md) - Comprehensive manual testing guide
  255. - [Feature Specification](docs/testing/FEATURE_SPEC.md) - Complete feature documentation
  256. - [Test Progress](docs/testing/TEST_PROGRESS.md) - Current test coverage status
  257. ## Configuration
  258. The server works out-of-the-box with sensible defaults. For advanced configuration:
  259. ### Environment Variables
  260. Create a `.env` file in the project root:
  261. ```bash
  262. # Authentication server (PRO features)
  263. AUTH_BASE_URL=https://blueprint-mcp.railsblueprint.com
  264. # Local WebSocket port (Free tier)
  265. MCP_PORT=5555
  266. # Debug mode
  267. DEBUG=false
  268. ```
  269. ### Command Line Options
  270. ```bash
  271. blueprint-mcp --debug # Enable verbose logging
  272. blueprint-mcp --port 8080 # Use custom WebSocket port (default: 5555)
  273. blueprint-mcp --debug --port 8080 # Combine options
  274. ```
  275. **Note:** If you change the port, you'll need to update your browser extension settings to match.
  276. ## Troubleshooting
  277. ### Extension won't connect
  278. 1. Check the extension is installed and enabled
  279. 2. Click the extension icon - it should show "Connected"
  280. 3. Check the MCP server is running (look for process on port 5555)
  281. 4. Try reloading the extension
  282. ### "Port 5555 already in use"
  283. Another instance is running. You can either:
  284. 1. Kill the existing process:
  285. ```bash
  286. lsof -ti:5555 | xargs kill -9
  287. ```
  288. 2. Use a different port:
  289. ```bash
  290. blueprint-mcp --port 8080
  291. ```
  292. ### Browser tools not working
  293. 1. Make sure you've called `enable` first
  294. 2. Check you've attached to a tab with `browser_tabs`
  295. 3. Verify the tab still exists (wasn't closed)
  296. ### Getting help
  297. - [GitHub Issues](https://github.com/railsblueprint/blueprint-mcp/issues)
  298. - [Documentation](https://blueprint-mcp.railsblueprint.com/docs)
  299. ## Contributing
  300. We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
  301. ## Security
  302. This tool gives AI assistants control over your browser. Please review:
  303. - The MCP server only accepts local connections by default (localhost:5555)
  304. - PRO relay connections are authenticated via OAuth
  305. - The extension requires explicit user action to connect
  306. - All browser actions go through the browser's permission system
  307. Found a security issue? Please email security@railsblueprint.com instead of filing a public issue.
  308. ## Credits
  309. 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.
  310. **Key differences:**
  311. - Uses browser extensions with DevTools Protocol (not Playwright)
  312. - Works with real browser profiles (not isolated contexts)
  313. - WebSocket-based communication (not CDP relay)
  314. - Cloud relay option for remote access
  315. - Free and PRO tier model
  316. - Multi-browser support (Chrome, Firefox, Edge, Opera)
  317. We're grateful to the Playwright team for pioneering browser automation via MCP.
  318. ## License
  319. Apache License 2.0 - see [LICENSE](LICENSE)
  320. Copyright (c) 2025 Rails Blueprint
  321. ---
  322. **Built with ❤️ by [Rails Blueprint](https://railsblueprint.com)**
  323. [Website](https://blueprint-mcp.railsblueprint.com) •
  324. [GitHub](https://github.com/railsblueprint/blueprint-mcp) •
  325. [NPM](https://www.npmjs.com/package/@railsblueprint/blueprint-mcp)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.