WhittleBrowser MCP server
Commit Nov 12, 2026An open-source engine that lets AI agents use a Chromium browser with compact text representations and built-in privacy protections.
Also known as vasanth7781/whittlebrowser-engine, @whittlebrowser/engine
- Stars
- 1
- Tools
- 9
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- MIT
What is WhittleBrowser MCP?
WhittleBrowser is an open-source engine that lets AI agents use a Chromium browser with compact text representations and built-in privacy protections. It exposes 9 tools, such as observe, act, navigate.
Summary generated from the project's README
About WhittleBrowser MCP server
Providing AI agents with a secure and efficient way to interact with the web is what whittlebrowser-engine achieves. This open-source engine allows models to use a Chromium browser through a specialized protocol that converts web pages into compact, ref-stable text representations. By using a diffing mechanism and pruning the DOM, it significantly reduces the number of tokens required for web navigation compared to standard browser tools.
Developers can integrate this engine into MCP clients like Claude Code, Cursor, or VS Code by running it via npx or as a TypeScript library. It prioritizes security by filtering out hidden prompt injections and sensitive secrets before they reach the LLM. The system also includes built-in protections that pause automation for sensitive sites like banking pages or irreversible actions, requiring human intervention for tasks like CAPTCHA or 2FA. Users can configure the server with various flags such as headless mode, specific browser channels, or custom risk settings to control how the agent behaves during web sessions.
What you can do with it
- 1Secure data extractionA developer can instruct an agent to scrape specific information from a page while ensuring private credentials remain hidden.
Written from the project's README. Every use case is checked against a quote from it.
How to install WhittleBrowser MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall WhittleBrowser MCP in Claude Code
$ claude mcp add whittlebrowser-engine -- npx -y @whittlebrowser/engineInstall WhittleBrowser MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"whittlebrowser-engine": {
"command": "npx",
"args": [
"-y",
"@whittlebrowser/engine"
]
}
}
}Install WhittleBrowser MCP in VS Code
.vscode/mcp.json
{
"servers": {
"whittlebrowser-engine": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@whittlebrowser/engine"
]
}
}
}Install WhittleBrowser MCP in VS Code CLI
$ code --add-mcp '{"name":"whittlebrowser-engine","type":"stdio","command":"npx","args":["-y","@whittlebrowser/engine"]}'Install WhittleBrowser MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"whittlebrowser-engine": {
"command": "npx",
"args": [
"-y",
"@whittlebrowser/engine"
]
}
}
}Install WhittleBrowser MCP in Codex
$ codex mcp add whittlebrowser-engine -- npx -y @whittlebrowser/engineInstall WhittleBrowser MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.whittlebrowser-engine] command = "npx" args = ["-y", "@whittlebrowser/engine"]
Install WhittleBrowser MCP in Gemini CLI
$ gemini mcp add -s user whittlebrowser-engine npx -- -y @whittlebrowser/engineInstall WhittleBrowser MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"whittlebrowser-engine": {
"command": "npx",
"args": [
"-y",
"@whittlebrowser/engine"
]
}
}
}WhittleBrowser MCP tools 9
Detected from the READMEobserveactnavigatefindextractresearchtabsscreenshotwait
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablevasanth7781/whittlebrowser-engine is public and reachablegithub.com/vasanth7781/whittlebrowser-engine ↗Pass
- Package names this repository as its source@whittlebrowser/engine names vasanth7781/whittlebrowser-engine as sourcenpmjs.com/package/@whittlebrowser/engine ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/vasanth7781/whittlebrowser-engine ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @whittlebrowser/enginePass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model9 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubWhittleBrowser
An open-source engine that lets AI agents use a Chromium browser. Pages are shown to models as compact, ref-stable, diffed text, secrets and hidden prompt injections are kept away from the LLM, and sensitive sites and irreversible actions wait for a person. It runs as an MCP server and as a TypeScript library.
packages/engine: the protocol (in-page agent in a CDP isolated world, serializer, differ, privacy filter, detectors), a Playwright/CDP driver and an MCP server (whittlebrowser).- The WhittleBrowser desktop browser (per-site AI, X-ray, ghost cursor, built-in chat, Demo Studio) is developed in a separate repository and is not released yet. The engine here works on its own with any MCP client.
website: the landing page, the Cloud waitlist, the Mac app "coming soon" page and the docs site (pnpm --filter @whittlebrowser/website dev; deploy notes in website/DEPLOY.md).
npm: @whittlebrowser/engine · Docs: docs/ · Issues: GitHub
See docs/COMPARISON.md for how it compares, docs/PROTOCOL.md for the format, and docs/BENCHMARK.md for the numbers.
Benchmark: WhittleBrowser vs Playwright MCP, browser-use and Stagehand
Same 11 pages (5 test pages + 6 live sites), same Chromium, each tool's own code, o200k tokens, no LLM calls. Full methodology and charts are in docs/BENCHMARK.md.
| Playwright MCP | browser-use | Stagehand | WhittleBrowser | |
|---|---|---|---|---|
| page text, 11 pages | 300,898 | 29,836 (+ screenshots) | 172,176 | 13,282 |
| all-in incl. prompts/tool defs/screenshots | 342,115 | 167,061 | 179,557 | 23,699 |
| WhittleBrowser uses | 93% fewer | 86% fewer | 87% fewer | |
| planted secrets reaching the model | 7 / 7 | 6 / 7 | 6 / 7 | 0 / 7 |
| hidden prompt injections reaching the model | 5 / 5 | 3 / 5 | 4 / 5 | 0 / 5 |
With a real model driving each tool (Claude Haiku and Sonnet through Claude Code, 7 tasks, 3 repetitions each), the saving on whole tasks is smaller and depends on the task: large or re-rendering pages save the most, small pages save little. Every tool finished most tasks; the numbers after the dot are tasks passed.
Regenerate the charts after a new run with pnpm --filter @whittlebrowser/engine bench:charts.
Install
Needs Node 22 or newer, and either Google Chrome or a downloaded Chromium (npx playwright-core install chromium, once).
The package is on npm: @whittlebrowser/engine.
claude mcp add whittlebrowser -- npx -y @whittlebrowser/engine # Claude Code
codex mcp add whittlebrowser -- npx -y @whittlebrowser/engine # Codex
Server flags go after the package name, for example … @whittlebrowser/engine --headless. For Cursor, VS Code, Gemini CLI and
other clients, put "command": "npx", "args": ["-y", "@whittlebrowser/engine"] in their MCP config. Claude Desktop needs full
paths instead (it does not see a Node installed with nvm); see docs/use-with-ai-tools.md.
Optional: npm i -g @whittlebrowser/engine installs the whittlebrowser command, and npx -y @whittlebrowser/engine install-skill installs the Claude skill that teaches a model to use the tools well.
Work on the engine (from source)
git clone https://github.com/vasanth7781/whittlebrowser-engine.git && cd whittlebrowser-engine
pnpm install
pnpm --filter @whittlebrowser/engine build
npx playwright-core install chromium # once
pnpm test # engine unit + browser + MCP tests (headless)
pnpm bench # benchmark (add -- --live --pw-mcp; run packages/engine/bench/compare/setup.sh once for browser-use + Stagehand)
Connect a source checkout to your tools
pnpm connect # adds the server to Claude Code, and prints the JSON for Cursor, VS Code and other clients
pnpm connect codex # adds it to Codex instead
pnpm connect desktop # adds it to Claude Desktop (then quit and reopen the app)
pnpm connect skill # installs the skill that teaches Claude how to use the tools well; pnpm connect all does everything
That runs claude mcp add whittlebrowser -- node <this checkout>/packages/engine/dist/mcp/cli.js (or codex mcp add …). Any extra arguments go to the
server, for example pnpm connect --headless. Setup for each client: docs/use-with-ai-tools.md.
Flags: --headless, --ephemeral, --profile DIR, --channel chrome, --budget N,
--allow-site HOST (override auto-pause), --risk confirm|auto|deny, --robots off|warn|enforce,
--default-off, --no-identify, --allow-file-urls, --humanize, --host (use a host app's policy, see docs/CONTROL.md), --bot-key FILE --bot-agent URL (Web Bot Auth).
Secrets for type secret:NAME: env WB_SECRET_NAME=… or ~/.whittlebrowser/secrets.json (chmod 600).
Tools
Nine MCP tools with short schemas (the whole list is about 1,000 tokens):
| Tool | What it does |
|---|---|
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) |
Full argument reference: docs/PROTOCOL.md.
How it stays cheap
- The in-page agent prunes the DOM in one pass: roles, accessible names, states, visibility, refs.
- The serializer flattens wrappers, merges inline runs, deduplicates labels, folds repeated siblings, and fits a token budget.
- Actions return outcome + diff, not the page. Steps can be batched.
findandextractanswer targeted questions without reading the whole page.
How it stays safe
- Isolated-world agent; hidden and deceptive text dropped; ⚠ on instruction-like text.
- Sensitive values masked in the page; one scrubbing choke point; reversible tokens; local vault.
- Per-site AI modes (
--default-off, or Off per site when a host app owns the policy), auto-pause on banking, consoles, and card/ID/key pages. - Approval for irreversible actions, data-carrying cross-site jumps, and uploads outside a sandbox dir.
- Honest identity: UA token, Web Bot Auth signatures, robots.txt, CAPTCHA handoff to the human. No fingerprint spoofing and no CAPTCHA solving.
Layout
packages/engine/src/page/agent.ts in-page agent (isolated world)
packages/engine/src/core/ serializer, diff, privacy, detector, injection, risk, robots, web bot auth
packages/engine/src/driver/ session (observe/act/find/extract/...), policy, launch
packages/engine/src/mcp/ MCP server + CLI
packages/engine/test, bench tests, fixtures, benchmark
website/ landing, Cloud waitlist, Mac page, docs site (renders docs/*.md)
License
MIT, see LICENSE. Contributions are welcome: see CONTRIBUTING.md. Report security issues privately, see SECURITY.md. The host control protocol that lets an app embed the engine is in docs/CONTROL.md.
WhittleBrowser MCP questions
How do I add WhittleBrowser MCP to Claude Code?
Run claude mcp add whittlebrowser-engine -- npx -y @whittlebrowser/engine in your terminal. Add --scope user to make it available in every project.
How do I add WhittleBrowser MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does WhittleBrowser MCP provide?
It exposes 9 tools, including observe, act, navigate, find, extract.
How does WhittleBrowser protect privacy?
It uses an isolated-world agent to drop hidden or deceptive text and masks sensitive values in the page through a single scrubbing choke point.
Does it support headless mode?
Yes, you can run the server with the --headless flag.
How does it handle CAPTCHAs or 2FA?
The engine can hand control over to a human for manual intervention during these processes.