Content
<div align="center">
<img src="assets/logo.svg" alt="byob" width="120"/>
# byob
**Bring Your Own Browser** — let your AI assistant use the Chrome you already have open.
[](LICENSE) [](https://modelcontextprotocol.io) [](https://developer.chrome.com/docs/extensions/mv3/intro/) [](CHANGELOG.md)
**English** · [中文](README.zh-CN.md)
</div>
---
byob is a local MCP server that lets AI coding tools (Claude Code, Cursor, Cline, Windsurf, etc.) directly control **your real Chrome** — the one where you're already logged into everything.
```
"read my Twitter timeline and summarize the top 5 posts"
"google 'mcp protocol spec', click the first result, read the page"
"take a screenshot of example.com"
"grab my GitHub session cookie so I can curl with it"
"open my Gmail tab and tell me how many unread"
```
| | WebFetch | Headless Puppeteer | **byob** |
|---|:-:|:-:|:-:|
| Sees logged-in pages | ❌ | ⚠️ manual cookie copy | ✅ already logged in |
| Passes bot detection | ❌ | ❌ | ✅ real human browser |
| Setup time | 0 | hours | **~5 min** |
| Cloud cost | free | $$ | free |
---
## Install
### Quick install (recommended)
```sh
curl -fsSL https://raw.githubusercontent.com/wxtsky/byob/main/install.sh | bash
```
The script checks prerequisites (Node.js ≥ 20, bun, Chrome), clones the repo, builds everything, and walks you through MCP registration interactively. If bun is not installed, it offers to install it for you.
> Set `BYOB_INSTALL_DIR` to change the install location (default: `~/byob`).
### Manual install
<details>
<summary>Prefer to do it yourself?</summary>
Requires **Node.js ≥ 20**, **bun**, **Chrome**, and any MCP-compatible AI tool.
```sh
git clone https://github.com/wxtsky/byob
cd byob
bun install
bun run setup
```
</details>
`bun run setup` handles the following automatically:
- Generates a unique extension key for you
- Builds the Chrome extension
- Writes the config that lets Chrome talk to byob
- Opens `chrome://extensions` automatically (macOS / Windows)
- Prints the **MCP server command** you'll need in Step 4
### Step 2 — Load extension in Chrome
The setup script opens `chrome://extensions` automatically on macOS / Windows. If it didn't open, navigate there manually.
1. Top-right → turn ON **Developer mode**
2. Top-left → click **Load unpacked**
3. Select the folder printed in your terminal, something like:
```
/your/path/to/byob/packages/extension/output/chrome-mv3
```
### Step 3 — Restart Chrome
**Quit Chrome completely** (`⌘Q` on Mac / close all windows on Windows), then reopen.
> Closing a single tab or window is not sufficient — Chrome only reads the Native Messaging config at startup.
### Step 4 — Register the MCP server with your AI tool
The setup script lets you choose your AI tool(s) interactively and registers automatically:
- **CLI tools** (Claude Code, Codex): runs the registration command directly
- **JSON-config tools** (Cursor, Windsurf, Cline): writes the config file for you
Reference for manual configuration:
<details open>
<summary><b>Claude Code</b></summary>
```sh
claude mcp add byob -s user -- /path/to/tsx /path/to/byob-mcp.ts
```
To enable `browser_eval`, add `-e BYOB_ALLOW_EVAL=1` after `-s user`.
</details>
<details>
<summary><b>Codex CLI</b></summary>
```sh
codex mcp add byob -- /path/to/tsx /path/to/byob-mcp.ts
```
</details>
<details>
<summary><b>Cursor</b></summary>
Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
```json
{
"mcpServers": {
"byob": {
"command": "/path/to/tsx",
"args": ["/path/to/byob-mcp.ts"]
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b></summary>
Add to `~/.codeium/windsurf/mcp_config.json` (same JSON format as Cursor):
```json
{
"mcpServers": {
"byob": {
"command": "/path/to/tsx",
"args": ["/path/to/byob-mcp.ts"]
}
}
}
```
</details>
<details>
<summary><b>Cline (VS Code)</b></summary>
Open Cline sidebar → MCP Servers → Configure, then add (same JSON format):
```json
{
"mcpServers": {
"byob": {
"command": "/path/to/tsx",
"args": ["/path/to/byob-mcp.ts"]
}
}
}
```
</details>
> The actual paths are printed by the setup script. The examples above use shortened paths for readability.
> To enable `browser_eval`, add `"env": { "BYOB_ALLOW_EVAL": "1" }` to the config (or `-e BYOB_ALLOW_EVAL=1` for CLI tools).
### Step 5 — Verify
```sh
bun run doctor
```
If all checks pass (4 green ✓), the installation is complete. Open a new session in your AI tool and try _"use byob to read ..."_.
---
## Tools
| Tool | What it does |
|---|---|
| `browser_read` | Open a page, scroll through, read all text |
| `browser_read_markdown` | Same, returns clean markdown (no nav/ads) |
| `browser_extract_table` | Pull `<table>` elements as JSON |
| `browser_get_console_logs` | Snapshot console.log / warn / error |
| `browser_start_record_network` | Start recording HTTP + WebSocket traffic |
| `browser_stop_record_network` | Stop recording, export JSON or HAR |
| `browser_screenshot` | Screenshot → saved to disk |
| `browser_download_images` | Download all images from a page |
| `browser_click` | Click a button or link |
| `browser_type` | Type into an input (optionally press Enter) |
| `browser_get_cookies` | Export cookies for `curl` / scripts |
| `browser_navigate` | Open a URL in a new or existing tab |
| `browser_wait_for` | Wait for an element to appear |
| `browser_list_tabs` | List all open tabs |
| `browser_switch_tab` | Switch to a tab |
| `browser_eval` | Run JavaScript on the page (off by default) |
9 of these tools support `framePath` to reach into nested iframes (including cross-origin).
Full schemas: [`shared/src/schemas.ts`](shared/src/schemas.ts)
---
## How it works
```
AI tool → byob-mcp → byob-bridge → Chrome extension → your tab
(stdio) (Unix socket) (Native Messaging) (Chrome DevTools Protocol)
```
All communication stays local. No data leaves your machine. When Chrome closes, all byob processes exit automatically.
---
## Everyday commands
```sh
bun run setup # install or re-install
bun run doctor # check what's working
bun run bridges # list running bridge processes
bun run logs # tail the bridge log
bun run unsetup # remove everything
```
All run from the byob repo root.
---
## Reliability
- **End-to-end cancellation.** `Ctrl+C` propagates through the entire chain (MCP → bridge → extension → Chrome), cleanly detaching all debug sessions.
- **DevTools conflict handling.** If DevTools is open on a tab, `browser_eval` automatically falls back to `chrome.scripting.executeScript`.
- **Sleep/wake recovery.** After a laptop sleep cycle, byob resets all debug sessions so the next call starts from a clean state.
---
## Security
- `browser_eval` is **off by default** — enable with `BYOB_ALLOW_EVAL=1`. Every call logs + notifies.
- `chrome://`, `file://`, Google/MS/Apple login pages are blocked by default.
- Each install gets a unique extension key — no collisions.
- Socket files are `0600`, dirs are `0700`. Other users can't see them.
- **Zero outbound network traffic.** No analytics, no pings, no crash reports.
- Chrome displays a "byob is debugging this browser" banner on active tabs. This is a Chrome security feature and cannot be suppressed.
---
## Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| `No live bridge` | Chrome not running or extension disabled | Check `chrome://extensions` |
| `cdp_attach_failed` | DevTools open on that tab | Close DevTools |
| `url_forbidden` | URL on the blocklist | See Security section |
| `extension_not_connected` | Extension lost connection | Reload at `chrome://extensions` |
| Nothing works after install | Chrome was not fully restarted | Quit Chrome completely (`⌘Q`) and reopen |
Run `bun run doctor` for detailed diagnostics on which step failed.
---
## Platform notes
| Platform | Auto | Manual |
|---|---|---|
| **macOS** | Opens `chrome://extensions` + prints MCP command | — |
| **Windows** | Same + writes config to registry | — |
| **Linux** | — | Open `chrome://extensions` and copy MCP command yourself |
---
## More
- [Changelog](CHANGELOG.md)
- [Contributing](CONTRIBUTING.md)
- [Design notes](docs/superpowers/specs/2026-04-25-byob-design.md)
- [Test checklist](docs/e2e-checklist.md)
MIT licensed. byob has broad access to your browser — only use it on machines and accounts you own.
