# Kb Browser > A browser you drive entirely from the CLI — Playwright + Chromium, DevTools in the terminal, restart-free proxy profiles, and an MCP server for AI agents (Claude Code). - **Type:** MCP server - **Install:** `agentstack add mcp-hiyokosauna37-kb-browser` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [HiyokoSauna37](https://agentstack.voostack.com/s/hiyokosauna37) - **Installs:** 0 - **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [HiyokoSauna37](https://github.com/HiyokoSauna37) - **Source:** https://github.com/HiyokoSauna37/kb-browser ## Install ```sh agentstack add mcp-hiyokosauna37-kb-browser ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About A browser you operate entirely from the command line. Built on Playwright + Chromium (CDP). = 18"> 日本語版は [README.ja.md](README.ja.md) を参照してください。 Everything a GUI browser gives you — page rendering, cookie management, DevTools operations (Network / Console / Elements) — is available as `kb` commands. FoxyProxy-style proxy profiles are built in, with **restart-free switching** and per-host routing rules. Designed to be driven by AI agents (Claude Code, etc.) via Bash or MCP, while the window is a real Chrome you can use by hand at any time. > **Two workflows it's built for:** > - **Drive it from an AI agent** — Claude Code and other agents operate kb over **MCP (24 tools)** or **Bash** (every command supports `--json`). The accessibility-snapshot + `--ref` loop is tuned for reliable, low-token automation, and the resident daemon returns each step in tens of milliseconds. > - **Security research & bug-bounty recon** (authorized testing only) — session-shared HTTP, live network inspection/mocking, raw `eval` on authenticated SPAs, proxy chaining into Burp/Caido, two-account IDOR via profiles, and masked, shareable evidence bundles. See [Security research & bug-bounty recon](#security-research--bug-bounty-recon). ## Features - **Daemon architecture** — the browser stays resident; every CLI command returns in tens of milliseconds - **Real Chrome** — uses your installed Chrome/Edge (DRM works), falling back to bundled Chromium; pick explicitly with `--channel`, override the User-Agent with `--ua`, or present as a regular (non-automation) browser with `--stealth` for authorized testing - **Attach to a running browser** — `kb daemon start --cdp http://127.0.0.1:9222` connects to a Chrome/Edge started with `--remote-debugging-port` and reuses its signed-in state - **Chrome extensions** — `kb daemon start --extensions ` loads unpacked extensions (`on` enables extensions already installed in the profile, `off` turns it back off). See [Chrome extensions](#chrome-extensions) - **Agent-optimized** — `kb snapshot` returns an accessibility tree with element refs; `kb click --ref e12` acts on them reliably (including inside iframes), and stale refs are **auto re-resolved** to the element with the same role/name after re-renders. Long outputs (text / html / snapshot) are capped at 20,000 chars by default with `--offset` paging. `kb eval` accepts `await` and multi-line code as-is - **DevTools from the terminal** — network log / response bodies (`kb net body`) / full headers (`kb net headers`) / request blocking / response mocking (including overriding live endpoints with error responses) / HAR recording / console / DOM inspection - **Mini REST client** — `kb request` hits APIs directly without opening a page; cookies and proxy settings are shared with the browser (call authenticated APIs as-is) - **Proxy profiles** — save `host:port` (+auth) as named profiles, switch instantly without restarting the browser, route specific hosts through specific proxies (FoxyProxy-style rules), SOCKS5 auth handled by the built-in relay (the relay itself is token-protected) - **Headed ⇄ headless / profile switching** — tabs and cookies survive - **Persistent sign-in** — log in once and the state is kept in the profile across sessions; `kb login` wraps the manual sign-in flow in one command, `kb storage dump / restore` exports it to a file - **Operation recording** — commands, network, and console are journaled by default; `kb log export` produces a self-contained bundle (report + reproduction steps + standalone curl + screenshots) with sensitive values masked by default - **Human-in-the-loop** — the agent automates, you take over for logins/CAPTCHAs, `kb wait` detects when you're done - **MCP server** — `kb-mcp` exposes 24 tools (screenshots are returned as images) - **`--json` everywhere** — machine-readable output for scripting and agents ## Install ```bash npm install npm run build npm link # makes kb / kb-mcp available globally ``` The browser binary is auto-selected: installed Chrome → Edge → Playwright's bundled Chromium (run `npx playwright install chromium` only if you need the bundled one). ## Quick start ```bash kb open example.com # daemon (browser) auto-starts kb text # read the page as text kb snapshot # page structure with element refs kb click --ref e6 # click reliably by ref kb screenshot -o s.png kb daemon stop # quit the browser ``` Headed (visible window) by default. Cookies and login state persist under `~/.kb/profiles/`. ## Commands | Category | Commands | |---|---| | Daemon | `kb daemon start [--headless] [--profile ] [--channel chrome\|msedge\|chromium] [--ua ] [--stealth] [--extensions ] [--cdp ] / stop / status` | | Pages | `kb open [-n] [--wait idle]` / `kb tabs [close/switch ]` / `kb text` / `kb html` / `kb snapshot` / `kb screenshot [\|--ref e12] [-f] [--timeout ]` (element-level supported) / `kb pdf` (headless only) | | Navigation | `kb back` / `kb forward` / `kb reload` / `kb scroll [--to /--bottom]` | | Interaction | `kb click` / `kb fill` / `kb select [--label]` / `kb check` / `kb uncheck` / `kb hover` / `kb upload ` / `kb press ` / `kb eval [--file f.js]` (`await` & multi-line OK; returns the last expression) — target via CSS selector, `--ref e12` (from snapshot), or `--frame ` (inside iframe) | | Dialogs | `kb dialog [show]` / `kb dialog accept [text]` / `kb dialog dismiss` / `kb dialog policy [hold\|accept\|dismiss]` (hold `alert`/`confirm`/`prompt`, then respond; default `hold`) | | HTTP | `kb request [-X POST] [-H "Name: value"] [-d body \| --data-file f] [-o file] [--no-follow \| --follow-verbose]` (page-independent; shares cookies & proxy with the browser) | | Login | `kb login [url] [--until ] [--save ]` (manual sign-in → state auto-saved to the profile) | | Cookies / session | `kb cookies [list/get/set/rm/clear/export/import]` / `kb storage dump/restore` | | Downloads | `kb downloads [list/clear]` (auto-saved under `~/.kb/downloads/`) | | Network | `kb net log [-f] [--filter re] [--responses]` / `kb net body ` (response body) / `kb net headers ` (full headers) / `kb net block ` / `kb net mock [--body f\|--text s] [--status n]` / `kb net unroute \|--all` / `kb net har start/stop` | | Console | `kb console [-f]` | | Recording | `kb log [list]` / `kb log start [--name n] [--shots] / stop / status` / `kb log show/steps [--no-mask]` / `kb log export [-o dir]` / `kb log replay [n] [--dry-run]` / `kb log rm ` | | DOM | `kb dom query [--html] [--attr name] [--frame ]` (falls back to same-name DOM property — value / checked etc. — when the attribute is absent) | | Proxy | `kb proxy add/rm/list/use/off/status/test` / `kb proxy rule add/rm/list` | | Mode / profile | `kb mode headed\|headless` / `kb profile list/use ` (tabs & cookies restored) | | Auth | `kb auth set ` / `kb auth clear` (HTTP Basic auth for target sites) | | Waiting | `kb wait [--url ] [--selector ] [--idle] [--any]` (multiple conditions AND by default, `--any` for OR) | | Emulation | `kb emulate ua/viewport/tz/geo/net/reset` (net: offline/slow3g/fast3g) | All commands support `--json`. Long outputs are truncated at 20,000 chars by default; use `--offset ` for the next chunk or `--max-chars 0` for everything. ## JS dialogs (alert / confirm / prompt) Pages that open `confirm` / `alert` / `prompt` on click work too. kb **holds** the dialog open and waits for a response (default `hold`), so the action result carries a `dialog`: ```bash kb click "#delete" # → clicked → confirm dialog "Are you sure?" is awaiting a response (tab 1). # Respond with kb dialog accept / kb dialog dismiss kb dialog # inspect the pending dialog kb dialog accept # OK (confirm → true, prompt → default value) kb dialog accept "Alice" # answer a prompt with text, then OK kb dialog dismiss # Cancel ``` While a dialog is pending, other actions on that tab (`snapshot` / `text` / `click` …) are guarded and prompt you to respond first. In headed mode the native dialog is shown on screen, so you can click OK / Cancel in the window directly — kb clears its pending state automatically. To auto-respond instead of holding: ```bash kb dialog policy accept # auto-OK every dialog (no display) kb dialog policy dismiss # auto-cancel every dialog (the old behavior) kb dialog policy hold # back to the default (hold and wait) ``` > Previously Playwright's default dismissed dialogs immediately, making buttons that trigger a `confirm` look like they "did nothing". `hold` fixes this — the dialog is shown to a human and you choose the response. ## Staying signed in **Sign in once.** kb launches the browser with a persistent profile (`~/.kb/profiles/`), so cookies and localStorage survive daemon restarts. For the initial sign-in to a service, use `kb login`: ```bash kb login github.com # switches to headed, opens the page → sign in → press Enter kb login myapp.example.com --until "**/dashboard**" # auto-detect completion by URL (agent-friendly) kb login github.com --save gh-state.json # also back the state up to a file ``` Subsequent sessions start already signed in — nothing to do. A `--save`d file can be carried to another profile or machine with `kb storage restore `. Note: sites that rely purely on session cookies (no expiry) sign you out on browser restart, same as a regular browser. `kb storage dump / restore` covers that case too. `storage dump` exports **all cookies including HttpOnly** plus localStorage (Playwright storageState format). To use two accounts at the same time, run a second daemon with its own `KB_HOME` (one daemon = one profile): ```bash KB_HOME=~/.kb-alt kb daemon start --profile account2 # runs alongside as an independent daemon ``` ## Attaching to a running browser Connect to a Chrome / Edge started with `--remote-debugging-port` instead of launching a new one — its signed-in state, extensions, and settings are used as-is: ```bash # 1. Start the target browser with CDP enabled (dedicated profile) chrome --remote-debugging-port=9222 --user-data-dir="%LOCALAPPDATA%\kb-attach" # 2. Attach kb to it kb daemon start --cdp http://127.0.0.1:9222 kb tabs # existing tabs are visible as-is kb open myapp.example.com # everything works as usual from here kb daemon stop # disconnects only; the target browser stays open ``` Constraints: - **Chrome 136+ disables remote debugging on the everyday default profile** (a security change). Start with a dedicated `--user-data-dir` as shown above and sign in to your services there once — the state sticks to that profile. - Since kb can't change how the target browser was launched, `kb mode` / `kb profile` / `kb auth` and kb's proxy-profile switching are unavailable while attached (they return a clear error). - Everything else — open / click / snapshot / eval / screenshot / net log / net body / cookies / storage — works. ## Chrome extensions Playwright launches Chromium with extensions disabled (`--disable-extensions`) by default; `--extensions` lifts that: ```bash kb daemon start --extensions "C:\dev\my-extension" # load unpacked extension(s), comma-separated kb daemon start --extensions on # enable only (use extensions already installed in the profile) kb daemon start --extensions off # back to disabled (the default) ``` - **Unpacked extensions** — point at a directory containing `manifest.json` (`.crx` files are not supported). Handy for developing and testing your own extension. - **Store extensions** — start with `--extensions on` in headed mode and install from the Chrome Web Store in the window as usual (chrome channel recommended). They persist in the profile, so subsequent starts only need `--extensions on`. - Like `--channel` / `--ua`, the setting carries over to the next auto-spawn; reset with `--extensions off`. Constraints: - **Unpacked extensions load via the bundled Chromium** (when directories are given, channel auto-selection picks bundled Chromium). Chrome 137+ stable removed the `--load-extension` flag, so real Chrome can't load them (`--extensions on` for profile-installed extensions works on any channel). - Works headless too (the extension-capable new headless mode is selected automatically). - Mutually exclusive with `--cdp` (attach) — extensions installed in the attached browser itself work as-is. ## API debugging When your API returns something unexpected, read the body right away — no HAR recording needed: ```bash kb net log --filter "api" # note the #seq at the start of each line kb net body 42 # print that response body (JSON reads as-is) kb net headers 42 # all request/response headers (cookies, cache-control, …) ``` To see how the UI handles errors, override a live endpoint in place: ```bash kb net mock "**/api/users" --status 500 --text '{"error":"internal"}' # matching requests now return 500 kb reload # inspect the error state kb net unroute 1 # back to normal ``` Bodies are captured automatically for text-like (JSON / HTML / JS / XML …) XHR / fetch / document responses. Capture is truncated at **256 KB per response** (32 MB / 500 entries total, oldest evicted first): `--offset` pages within the captured part, but anything beyond 256 KB is not recoverable afterwards — if you need the full body of a large response, re-fetch it with `kb request -o `. To hit an endpoint directly, use `kb request` (a mini REST client): ```bash kb request localhost:3000/api/users # GET kb request localhost:3000/api/users -X POST -d '{"name":"a"}' # JSON bodies get Content-Type: application/json automatically kb request api.example.com/v2/me -H "Accept: application/vnd.api+json" -H "X-Api-Version: 2" ``` Explicit `-H` headers always win (JSON auto-detection only kicks in when Content-Type is unset). No page needed, and **cookies & proxy settings are shared with the browser** — if you're logged in in the browser, authenticated APIs just work, and `Set-Cookie` responses flow back into the browser. Save binary responses with `-o `. Response **`Set-Cookie` headers are shown by default, one per line** (multiple cookies stay parseable instead of being folded into a single line), and `-i` prints all response headers (MCP: `includeHeaders`). With `--json`, `result.setCookies` holds the individual `Set-Cookie` values as an array (masked like other sensitive headers in `kb log export` bundles). ```bash kb request localhost:3000/api/login -X POST -d '{"user":"a"}' # Set-Cookie: sid=… is shown above the body kb request localhost:3000/api/me -i # all response headers + individual Set-Cookie ``` Redirects are followed by default. Use `--no-follow` to stop at the 3xx, or **`--follow-verbose`** to follow while printing every hop's status / `Location` / `Set-Cookie` — useful for seeing where a chain lands and which cookies get set mid-redirect (method handling matches browsers: 303 and POST-on-301/302 become GET; 307/308 preserve). With `--json`, the intermediate hops are in `result.hops`. ```bash kb request example.com/login --follow-verbose # 302 → 301 → 200, each hop with its Set-Cookie kb request example.com/old-path --no-follow # show the 3xx itself instead of the final target ``` ## Operation recording & shareable bundles The daemon **records operations by default** (commands, xhr/fetch/document traffic, console output). After a work session, one command produces a self-contained bundle that **someone without kb can read and reproduce**: ```bash kb log export # generates ./kb-log-/ kb log export -o out --no-mask --allow "^cookie$" --deny "internal\.corp" ``` ``` kb-log-/ ├─ report.md # numbered steps + per-step … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [HiyokoSauna37](https://github.com/HiyokoSauna37) - **Source:** [HiyokoSauna37/kb-browser](https://github.com/HiyokoSauna37/kb-browser) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-hiyokosauna37-kb-browser - Seller: https://agentstack.voostack.com/s/hiyokosauna37 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.