⚡ @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?

📚 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.