bb-browser

What It Does

bb-browser is a CLI tool and MCP server that connects AI agents to your real Chrome browser via the Chrome DevTools Protocol (CDP). Instead of using headless browsers or scraping libraries, it runs JavaScript inside your actual browser tabs where you are already logged in. The tool ships 143 community-maintained site adapters that turn popular websites (Twitter, Reddit, GitHub, YouTube, Zhihu, Bilibili, and 30 more) into structured CLI commands. It also provides general browser automation: opening URLs, clicking elements, filling forms, taking screenshots, and executing arbitrary JavaScript in page context.

The target user is an AI agent developer who needs their agent to interact with authenticated web services. It works as a standalone CLI or as a Model Context Protocol server for integration with Claude Code, Cursor, and other agent frameworks.

The Good

143 community adapters with zero API keys required. The site update command clones the bb-sites repository and installs 143 adapters covering search engines, social media, developer tools, video platforms, finance sites, and more. Each adapter is a single JavaScript file that reverse-engineers the site's internal API. Running bb-browser site arxiv/search "transformer" returns structured JSON with no API key, no OAuth flow, no scraping setup.

Well-structured MCP server with session management. The 713-line MCP server (packages/mcp/src/index.ts) auto-discovers and registers tools from a shared COMMANDS registry. It tracks which tabs were opened during the current session and provides a browser_close_all tool that cleans up on exit. The daemon auto-starts when the MCP server initializes, handling the full lifecycle without manual intervention.

Clean monorepo architecture with strong invariants. The codebase splits into four packages: shared (protocol types), daemon (CDP connection and command dispatch), cli (user-facing commands), and mcp (MCP server). The AGENTS.md file documents seven design invariants (e.g., "all operation responses must include tab and seq", "per-tab event isolation"). The command dispatch alone is 1,103 lines with per-tab state management and ring buffers for network, console, and error events.

Adapter development workflow is thoughtful. The bb-browser guide command walks through creating new adapters. The AGENTS.md defines three tiers of complexity: cookie-based fetch (1 minute), bearer token extraction (3 minutes), and webpack/Pinia injection (10 minutes). The network --with-body command captures full request/response pairs for reverse engineering. This is a real developer experience, not just documentation.

The Bad

Requires Chrome with remote debugging enabled. The entire toolchain depends on a running Chrome instance with --remote-debugging-port. If Chrome is not running or the flag is not set, the daemon fails immediately. This is a hard requirement that limits deployment to machines where you control the browser startup. Headless server environments, CI pipelines, and containers need extra setup.

Monorepo requires pnpm for local development. The project uses pnpm workspaces and turbo for builds. The package.json specifies "packageManager": "pnpm@9.15.0". Attempting to build with npm fails with dependency resolution errors and missing workspace links. This is fine for users who just npm install -g bb-browser, but anyone contributing or debugging locally must install pnpm first.

npm cache permission issues on macOS. The npm global install failed on this test machine because the npm cache directory contained root-owned files from a previous sudo install. This is a recurring npm problem on macOS, not specific to bb-browser, but it does affect the first-run experience. The workaround (npx -y bb-browser) works fine.

Documentation is bilingual but English-only readers may miss context. The SKILL.md files and AGENTS.md mix Chinese and English. The CLI help text is in Chinese by default. This is not a blocker but may confuse some users. The README has both English and Chinese versions.

Smoke Test Results

Tested on macOS (26.4.1, aarch64) with Node.js v24.13.1. Chrome was not available with remote debugging enabled, so browser commands could not be tested.

Install

$ npx -y bb-browser --version

✅ 0.11.6

$ npx -y bb-browser --help

✅ bb-browser - AI Agent 浏览器自动化工具

(shows full help with site commands, browser operations, tab management)

$ npx -y bb-browser site list

✅ (initially empty array)

$ npx -y bb-browser site update

✅ 克隆社区 adapter 库: https://github.com/epiral/bb-sites.git

已安装 143 个社区 adapter。

$ npx -y bb-browser site list

✅ 244 lines of output covering 36 platforms and 143 adapters

$ npx -y bb-browser site info arxiv/search --json

✅ { "name": "arxiv/search", "description": "Search arXiv papers by query",

"domain": "arxiv.org", "args": { "query": { "required": true } },

"example": "bb-browser site arxiv/search \"large language model\"",

"readOnly": true }

$ npx -y bb-browser daemon status

✅ Daemon not running

💡 启动: bb-browser daemon start

Pass rate: 6 of 6. All CLI commands that do not require a running browser executed correctly.

Tools respond

$ npx -y bb-browser --mcp

❌ Could not test: MCP server starts a stdio transport and waits for input. No daemon or Chrome running.

$ npx -y bb-browser site arxiv/search "transformer"

❌ Could not test: daemon is not running, Chrome not available.

Pass rate: 0 of 2. Browser-dependent commands require Chrome with remote debugging.

What the runs tell you

The CLI installs and runs cleanly. The site adapter system downloads and indexes 143 adapters without issues. The missing piece is the daemon and Chrome connection, which is the core value proposition. Without a Chrome instance to connect to, the tool is a very well-structured shell waiting for its runtime. The MCP server is confirmed to register tools from the COMMANDS registry by reading the source code, but could not be exercised live.

Setup Walkthrough

1. Install globally: npm install -g bb-browser (or use npx -y bb-browser to skip install).
2. Download community adapters: bb-browser site update (clones bb-sites repo, ~143 adapters).
3. Start Chrome with remote debugging: google-chrome --remote-debugging-port=19825 (or let bb-browser manage Chrome startup).
4. Start the daemon: bb-browser daemon (or let it auto-start when you run a command).
5. Run a site adapter: bb-browser site arxiv/search "AI agent".
6. For MCP integration, add to your agent config: {"command": "npx", "args": ["-y", "bb-browser", "--mcp"]}.

The main friction point is step 3. Chrome must be running with the debugging port open before the daemon can connect. The daemon writes a ~/.bb-browser/daemon.json file with its PID, port, and auth token. The MCP server reads this file to discover the daemon.

Alternatives

1. Playwright MCP -- the official Playwright MCP server provides browser automation through a similar MCP interface, but uses its own browser instance without your login state. Better for testing, worse for authenticated data access.
2. Browserbase -- cloud-based browser automation platform with MCP support. Runs headless browsers in the cloud. Commercial product with pricing tiers. Solves the Chrome requirement but loses the "your real browser" advantage.
3. puppeteer / direct CDP -- for developers comfortable with the Chrome DevTools Protocol, connecting directly gives maximum control but requires writing all the adapter logic yourself. No community adapters, no CLI, no MCP server.