repository·main·Indexed 27 days ago
https://github.com/epiral/bb-browserA CLI tool and MCP server that turns a Chrome browser into an API for AI agents. It allows machines to use human interfaces and existing login states to access websites, bypassing anti-bot measures. Features include site-specific adapters, full browser automation (click, fill, eval, snapshot), network traffic capture, and a daemon for routing commands via HTTP API.
localhost. No data, telemetry, or analytics are sent to external servers or third parties.Every bb-browser site command MUST include the --openclaw flag. This ensures the command runs through OpenClaw's browser, allowing it to use your existing login state and avoiding the need for a separate Chrome extension or daemon.
If you omit --openclaw, the command will fail or require a separate Chrome extension.
# Correct usage
bb-browser site twitter/search "AI agent" --openclaw
bb-browser site zhihu/hot 10 --openclaw --json
# Wrong (requires separate Chrome extension)
bb-browser site twitter/search "AI agent"If you use OpenClaw, you can run bb-browser directly through its built-in browser without installing extra Chrome extensions or a daemon by using the --openclaw flag.
bb-browser site reddit/hot --openclaw
bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePercent}'You can connect bb-browser to AI coding agents like Claude Code or Cursor using the Model Context Protocol (MCP) by adding the following configuration to your MCP settings:
{
"mcpServers": {
"bb-browser": {
"command": "npx",
"args": ["-y", "bb-browser", "--mcp"]
}
}
}The Site system uses adapters to turn website features into CLI commands. It automatically handles tab management (finding existing tabs or creating new ones) and detects login errors.
# List all available adapters
bb-browser site list
# Search for an adapter
bb-browser site search <query>
# Run an adapter (syntax: bb-browser site <name> [args...])
bb-browser site twitter/search "Claude Code"
bb-browser site zhihu/hot
bb-browser site github/repo owner/repo
bb-browser site youtube/transcript <video_id>
# Update community adapters
bb-browser site updateTo use bb-browser with AI agents like Claude Code or Cursor, add it as an MCP (Model Context Protocol) server in your configuration file.
{
"mcpServers": {
"bb-browser": {
"command": "npx",
"args": ["-y", "bb-browser", "--mcp"]
}
}
}You can use the --jq flag to filter and extract specific fields from the JSON output returned by adapters. When using --jq, the --json flag is implied and does not need to be explicitly provided.
# Just stock names
bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[].name'
# Specific fields as objects
bb-browser site xueqiu/hot-stock 5 --openclaw --jq '.items[] | {name, changePercent, heat}'
# Filter results
bb-browser site reddit/hot --openclaw --jq '.posts[] | {title, score}'The fetch command allows you to execute fetch() calls within the browser context. This is essentially a version of curl that automatically carries cookies and existing login states from the browser.
Automatic Domain Routing:
/api/me.json): Uses the origin of the currently active tab.https://www.reddit.com/...): Searches for an existing tab with a matching domain. If none is found, it automatically opens a new tab and waits 3 seconds before executing the fetch in that new tab's context.Response Handling:
--output automatically formats and writes the response to the specified file.The Site system turns websites into CLI APIs using adapters. Each adapter is a JS file that executes in a real browser, reusing your login session and returning structured JSON.
bb-browser site list (groups by platform)bb-browser site search <query> (matches name, description, or domain)bb-browser site <name> [args...]bb-browser site run <name> [args...]bb-browser site update (pulls from github.com/epiral/bb-sites)bb-browser guideFor Single Page Applications (SPAs) like Twitter/X where Webpack module IDs change frequently, do not hardcode IDs. Instead, dynamically find modules by searching for stable code signatures or operationName in GraphQL queries.
// 1. Get webpack require
let __webpack_require__;
const chunkId = '__bb_' + Date.now();
window.webpackChunk_twitter_responsive_web.push(
[[chunkId], {}, (req) => { __webpack_require__ = req; }]
);
// 2. Find module by signature (e.g., finding a transaction generator)
let genTxId;
for (const id of Object.keys(__webpack_require__.m)) {
const src = __webpack_require__.m[id].toString();
if (src.includes('jf.x.com') && src.includes('jJ:')) {
genTxId = __webpack_require__(id).jJ;
break;
}
}
// 3. Find GraphQL queryId by operationName
let queryId;
for (const id of Object.keys(__webpack_require__.m)) {
const src = __webpack_require__.m[id].toString();
const m = src.match(/queryId:"([^" ]+)",operationName:"CreateTweet"/);
if (m) { queryId = m[1]; break; }
}Install the bb-browser CLI globally to start using your browser as an API for AI agents and automation.
npm install -g bb-browserTo avoid Ref not found errors, follow these patterns:
bb-browser snapshot -i again.bb-browser snapshot -i to get the new elements' refs.bb-browser wait <ms> before snapshotting.# Correct pattern for AJAX/Dynamic content
bb-browser click @3
bb-browser wait 1000
bb-browser snapshot -i