bunbrowser

⚡ @bunbrowser/mcp

Ultra-fast, zero-download Model Context Protocol (MCP) server for browser automation, powered natively by Bun.WebView.

A 100% drop-in lightweight replacement for @playwright/mcp with identical AI tool semantics, native isTrusted: true OS events, sub-50ms startup times, and zero binary bloat.

---

🚀 Why bunbrowser?

Feature	@playwright/mcp (Official Playwright)	@bunbrowser/mcp (Native Bun.WebView)
Startup Latency	~500ms - 2.5s cold start	< 50ms (Instantaneous)
Binary Downloads	~300MB - 1GB dedicated browser packages	0 MB (Uses Chrome/Chromium on Linux/Win or WKWebView on macOS)
Base Memory Footprint	~180MB - 350MB RAM	~25MB - 50MB RAM
Event Fidelity	Synthetic via CDP JavaScript injection	Native OS-level compositor events (isTrusted: true)
Accessibility Tree	browser_snapshot with [ref=eN]	Identical [ref=eN] format and prompt compatibility
Batch Form Filling	Individual turns for each field	Single-turn browser_fill_form
Performance & SEO	Requires custom scripts	Built-in browser_lighthouse_audit (0-100 scores) & browser_get_metrics
Motion & Animation	Not exposed directly	Built-in browser_record_animation (WebM & animated GIF)
Raw CDP Access	Restricted	Built-in browser_cdp tool

---

📚 Official Documentation (Diátaxis Framework)

The project documentation is structured using the Diátaxis Framework:

• 🎓 Tutorials (Learn from scratch): Guided onboarding, installation, and your first AI automation.
• 🛠️ How-To Guides (Practical recipes):
  • Configuring AI Clients (Claude Desktop, Cursor, Antigravity, VS Code)
  • Optimal Agent Prompting & Tool Selection
  • Recording Videos & Debugging Animations
  • Persisting Sessions, Cookies, and LocalStorage
  • Executing Direct CDP Commands
• 📖 Technical Reference (Specifications):
  • Complete Catalog of all 30 MCP Tools & Schemas
  • Command-Line Options (CLI) & Environment Variables
• 💡 Explanation & Architecture (Concepts):
  • Internal Architecture & Native Events (isTrusted: true)
  • Detailed Technical Comparison vs. @playwright/mcp

For a complete navigation map, see docs/index.md.

---

📦 Installation & Setup

1. Requirements

• Bun (v1.3.12 or higher).
• On macOS: Zero additional downloads (uses built-in WKWebView).
• On Linux / Windows: Google Chrome, Chromium, Brave, or Microsoft Edge installed.

2. Configure in your MCP Client

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "playwright": {
      "command": "bunx",
      "args": ["@bunbrowser/mcp"]
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "browser": {
      "command": "bunx",
      "args": ["@bunbrowser/mcp"]
    }
  }
}

Google Antigravity (~/.gemini/antigravity/mcp_config.json):

{
  "mcpServers": {
    "browser": {
      "command": "bunx",
      "args": ["@bunbrowser/mcp"]
    }
  }
}

CLI Execution with Custom Viewport:

bunx @bunbrowser/mcp --width 1920 --height 1080 --url "https://bun.sh"

---

🛠️ Complete MCP Tools Catalog (30 Tools)

🌐 Navigation

• browser_navigate: Navigate to a URL with optional accessibility snapshot.
• browser_navigate_back: Navigate back in history.
• browser_navigate_forward: Navigate forward in history.
• browser_reload: Reload active page.

🔍 Inspection & State

• browser_snapshot: PRIMARY INSPECTION. Captures semantic accessibility tree with [ref=eN] IDs.
• browser_take_screenshot: Visual viewport screenshot in Base64 (PNG, JPEG, WebP) or direct zero-copy disk save.
• browser_evaluate: Evaluates JavaScript in page context.
• browser_get_content: Returns full HTML markup or plain text.
• browser_console_logs: Retrieves recorded console logs.

🖱️ Element Interaction

• browser_click: Clicks element via ref, CSS selector, or coordinates.
• browser_type: Types text into input elements with auto-wait.
• browser_fill_form: BATCH FORM FILLER. Fills multiple inputs and submits in a single turn.
• browser_press_key: Dispatches keyboard keys and key combinations.
• browser_hover: Moves mouse pointer over an element.
• browser_scroll: Directional, delta-based, or element-targeted scrolling.
• browser_select_option: Selects options in <select> dropdowns.
• browser_drag: Drag-and-drop between source and destination elements.

📑 Tab Management

• browser_tabs: Lists all open tabs and active state.
• browser_tab_new: Opens a new tab with optional URL and viewport size.
• browser_tab_switch: Switches active tab focus by tabId.
• browser_tab_close: Closes a specific tab or active tab.
• browser_resize: Resizes viewport dimensions.

⚡ Storage & CDP

• browser_cdp: Executes raw Chrome DevTools Protocol commands.
• browser_cookies: Gets, sets, or clears browser session cookies.
• browser_localstorage: Gets, sets, or clears localStorage keys.

📊 Performance & Lighthouse Audits

• browser_get_metrics: Real-time network timings (TTFB, DOM load), JS heap memory, and resource waterfalls.
• browser_lighthouse_audit: Full Lighthouse audit with 0-100 scores for Performance, Accessibility, Best Practices, and SEO.

🎬 Video Recording & Motion

• browser_start_recording: Starts continuous video recording (webm or gif) with scaling, compression quality, and click ripples.
• browser_stop_recording: Stops recording and exports file with duration, frame count, dimensions, and size metrics.
• browser_record_animation: One-shot recording of UI transitions and keyframe animations for a given durationMs with trigger actions.

---

🧪 Automated Testing

Run the complete test suite:

# Run unit & integration tests
bun test

# Verify strict TypeScript types
bun run check

---

📂 Codebase Structure

bunbrowser/
├── bin/
│   ├── bunbrowser.ts         # CLI binary executable
│   └── bunpw-mcp.ts          # Legacy compatibility wrapper
├── src/
│   ├── index.ts              # Entrypoint CLI & Stdio transport
│   ├── server.ts             # McpServer instance & tool registration
│   ├── browser/
│   │   ├── types.ts          # TypeScript interfaces & configuration types
│   │   ├── manager.ts        # BrowserManager (multi-tab lifecycle)
│   │   ├── tab.ts            # BrowserTab wrapper over Bun.WebView
│   │   ├── recorder.ts       # TabRecorder video & animation capture
│   │   ├── gif_encoder.ts    # Pure TypeScript GIF89a encoder (0 dependencies)
│   │   └── snapshot.ts       # Accessibility Tree & ref resolver
│   └── tools/
│       ├── navigation.ts     # Navigation tools
│       ├── inspection.ts     # Snapshot, screenshot, evaluate, content, logs
│       ├── interaction.ts    # Click, type, fill_form, press_key, hover, scroll, drag
│       ├── tabs.ts           # Tabs management & resize
│       ├── storage_cdp.ts    # CDP, cookies, localStorage
│       ├── metrics.ts        # get_metrics, lighthouse_audit
│       └── video.ts          # start_recording, stop_recording, record_animation
├── test/
│   ├── manager.test.ts       # Tab manager tests
│   ├── snapshot.test.ts      # Accessibility tree tests
│   ├── interaction.test.ts   # Real DOM interaction tests
│   ├── metrics.test.ts       # Metrics & Lighthouse audit tests
│   ├── video.test.ts         # Video recording & GIF encoder tests
│   └── mcp_server.test.ts    # End-to-end MCP JSON-RPC tests
└── docs/                     # Diátaxis framework documentation
    ├── 1-tutorials/
    ├── 2-how-to/
    ├── 3-reference/
    └── 4-explanation/

---

📄 License

MIT License. See LICENSE for details.