# @whittlebrowser/engine [Health: Active]

**Category:** 📂 Browser Automation  
**Repository:** https://github.com/vasanth7781/whittlebrowser-engine  
**GitHub Stars:** 1  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/whittlebrowser-engine

## Description
Token-lean, ref-stable, privacy-first browser protocol for AI agents (core + Playwright/CDP driver + MCP server).

## Tools
Capabilities this server exposes over MCP:

- **observe** — Compact view of the page (or one subtree) within a token budget
- **act** — One or more steps (click, type, select, check, hover, press, scroll, upload); returns outcome + diff
- **navigate** — URL, search words, back, forward, reload
- **find** — Search the whole page, including off-screen, ranked. `role:button pay` filters by role; `css:SELECTOR` counts visible matches and lists their class and attributes
- **extract** — table`, `list` (repeated cards as rows), `text` (main content as markdown), paged
- **research** — Open several pages in parallel and return a compact digest of each
- **tabs** — list, open, switch, close
- **screenshot** — JPEG with sensitive fields blurred (last resort)
- **wait** — For text, for a delay, or hand control to you (CAPTCHA, 2FA)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "engine": {
    "command": "npx",
    "args": ["-y","playwright-core"]
  }
}
```

## Documentation

## What @whittlebrowser/engine does

@whittlebrowser/engine gives AI agents an MCP interface to Chromium. It is available as an npm package, a command-line MCP server, and a TypeScript engine library. The browser page is represented as compact text with stable references, rather than sending the complete DOM or relying on screenshots for ordinary interactions.

The engine also applies privacy and safety handling before page content reaches the model. Sensitive values can be masked, hidden or deceptive text can be removed, and instruction-like content can be marked. Site and action policies can pause activity on banking, payment, identity, console, and key pages, while irreversible actions, certain cross-site data transfers, and unsandboxed uploads can require approval.

## How it works

An in-page agent runs in a CDP isolated world and gathers visible roles, accessible names, states, and references. A serializer removes unnecessary wrappers, combines inline content, deduplicates labels, folds repeated elements, and fits the result to a requested token budget. Actions return an outcome and a change diff, so an agent does not need to reread the entire page after each step.

Targeted operations reduce unnecessary page inspection. `find` searches the complete page, including off-screen content, while `extract` can return tables, repeated card-like lists, or main text as Markdown. `research` opens multiple pages in parallel and produces a compact digest for each. The engine can also honor robots.txt modes, identify itself through a user-agent token, and use Web Bot Auth signatures when configured.

## Setup and configuration

The package requires Node.js 22 or newer and either Google Chrome or a locally installed Chromium. Install Chromium with `npx playwright-core install chromium` when needed, then register the package with an MCP client using `npx -y @whittlebrowser/engine`.

Claude Code and Codex provide dedicated commands. Cursor, VS Code, Gemini CLI, and other clients can use an MCP configuration whose command is `npx` with arguments `-y` and `@whittlebrowser/engine`. Claude Desktop may require absolute executable paths, particularly when Node.js was installed through nvm. A global npm install also provides the `whittlebrowser` command.

Server options include `--headless`, `--ephemeral`, `--profile DIR`, `--channel chrome`, `--budget N`, `--allow-site HOST`, `--risk confirm|auto|deny`, and `--robots off|warn|enforce`. Additional controls cover default-off site behavior, file URLs, humanized interaction, host policy integration, and Web Bot Auth. Values referenced as `type secret:NAME` can come from `WB_SECRET_NAME` or `~/.whittlebrowser/secrets.json` with restricted permissions.

## Tools and capabilities

- `observe` returns a compact page or subtree view within a token budget.
- `act` batches clicks, typing, selection, checks, hovering, key presses, scrolling, and uploads, then returns the result and diff.
- `navigate` handles URLs, word searches, back, forward, and reload.
- `find` ranks page matches and supports role and CSS queries.
- `extract` returns tables, repeated-card lists, main text, and paged results.
- `research` processes several pages in parallel.
- `tabs` lists, opens, switches, and closes tabs.
- `screenshot` returns a JPEG with sensitive fields blurred.
- `wait` waits for text or a delay, or hands control to a person for CAPTCHA and 2FA.

## Limitations and notes

The engine does not solve CAPTCHAs or spoof browser fingerprints; it can pause and request human control instead. Screenshots are intended as a fallback rather than the normal page representation. The separate WhittleBrowser desktop application is developed elsewhere and is not part of this package; the engine works independently with MCP clients.

_Full upstream README: https://allmcps.com/mcp/whittlebrowser-engine/readme_