Content
# @yawlabs/vew-mcp
A browser MCP server that lets AI agents drive a real Chromium **optimally**. Bring-your-own client: runs as a stdio MCP server so any MCP-compatible client (Claude Code, Claude Desktop, Cursor, `mcph`, …) can browse the web through a single persistent page.
[](https://yaw.sh/mcp/install?name=Vew&command=npx&args=-y%2C%40yawlabs%2Fvew-mcp&description=Drive%20a%20real%20Chromium%20for%20AI%20agents%20-%20compact%20ref-addressable%20page%20snapshots&source=https%3A%2F%2Fgithub.com%2FYawLabs%2Fvew-mcp)
One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.
## Why a snapshot instead of the DOM
An agent driving a browser does not need the raw DOM — tens of thousands of tokens of markup, inline styles, and script. It needs to know *which elements it can act on*, *what each one is*, and *a handle to act on it*. That is what `browser_snapshot` returns:
```
# Login
URL: https://example.com/login
## Interactive elements
[e1] textbox "Email"
[e2] textbox "Password"
[e3] button "Sign in"
[e4] link "Forgot password?"
## Page text
Welcome back. Please sign in to continue...
```
Then you act by **ref**: `browser_type({ ref: "e1", text: "a@b.com" })`, `browser_click({ ref: "e3" })`. Every action returns a fresh snapshot, so you always act off the latest view.
**Refs are stable within a snapshot and renumber on the next one.** Always use a ref from the most recent snapshot; a stale ref returns an error rather than clicking the wrong element after the page changed. This is the same model vew's own agent layer uses.
## What it gives the model
| Tool | What it does |
|------|--------------|
| `browser_navigate` | Go to a URL, return a fresh snapshot of the loaded page |
| `browser_snapshot` | **Core** — compact ref-tagged element list + readable page text |
| `browser_click` | Click the element addressed by `ref`, return a fresh snapshot |
| `browser_type` | Type into the field addressed by `ref` (optionally submit), return a snapshot |
| `browser_scroll` | Scroll up / down / top / bottom, return a snapshot |
| `browser_back` / `browser_forward` | History navigation, each returns a snapshot |
| `browser_get_text` | Readable page text only (no element list) |
| `browser_screenshot` | PNG of the viewport or full page, as an image |
One persistent Chromium + one page per server process. The browser launches lazily on the first navigation and tears down cleanly when the client disconnects.
## Install & run
```bash
# One-off (auto-updates each spawn via @latest)
npx -y @yawlabs/vew-mcp@latest
# Or globally
npm i -g @yawlabs/vew-mcp
vew-mcp
```
Requires Node ≥22. The first run needs the Chromium browser that Playwright drives:
```bash
npx playwright install chromium
```
(One-time, ~150 MB. The server itself does not download it for you — keeping the npm package light.)
Set `VEW_HEADLESS=0` to watch the browser instead of running it headless.
### Driving an existing browser (Vew)
The default mode launches a self-owned headless Chromium. To drive an existing browser instead -- most commonly the Vew desktop browser when the user has enabled the MCP bridge in Vew's Agent panel -- set `VEW_CDP_URL` to the host's Chrome DevTools Protocol endpoint:
```bash
VEW_CDP_URL=ws://127.0.0.1:9222 npx -y @yawlabs/vew-mcp@latest
```
In attach mode the host owns the process lifetime: `VEW_HEADLESS` is ignored, and `vew-mcp` does not close the host's browser on exit -- it just disconnects. The active page is selected from the host's first browser context (the most-recently focused page). The threat model is wider than the default mode: a prompt-injected instruction that says "navigate to file:///etc/passwd" navigates the user's actual browser, with their cookies and authenticated sessions, not an isolated Playwright Chromium. Enable the bridge in Vew only when you trust the agent.
## Configure in Claude Code / Claude Desktop
Add to your client's MCP config (usually `claude_desktop_config.json` or `~/.claude.json`):
```json
{
"mcpServers": {
"vew": {
"command": "npx",
"args": ["-y", "@yawlabs/vew-mcp@latest"]
}
}
}
```
Or via `mcph`:
```bash
mcph add vew
```
## Tool reference
### `browser_navigate`
```ts
{
url: string; // absolute http/https URL
wait_until?: "load" | "domcontentloaded" | "networkidle" | "commit"; // default "load"
timeout_ms?: number; // default 30000
}
```
Navigates the persistent page and returns a fresh snapshot. Usually the first call.
### `browser_snapshot`
```ts
{
text_budget?: number; // max chars of page text (default 8000)
}
```
Returns the compact view of the **current** page: a ref-tagged element list followed by readable text. Each element line is `[ref] role "name"`, with optional trailing `(value: "...", checked, disabled)`. Prefer this over any raw-DOM approach.
### `browser_click`
```ts
{
ref: string; // e.g. "e3", from the most recent snapshot
timeout_ms?: number; // default 10000
}
```
Clicks the element and returns a fresh snapshot. Use for buttons, links, checkboxes, tabs, menu items.
### `browser_type`
```ts
{
ref: string; // a textbox/searchbox/combobox ref
text: string; // value to type (field is cleared first)
submit?: boolean; // press Enter after typing (default false)
timeout_ms?: number; // default 10000
}
```
Fills the field and optionally submits (e.g. to run a search). Returns a fresh snapshot.
### `browser_scroll`
```ts
{
direction: "up" | "down" | "top" | "bottom";
}
```
Scrolls one viewport (`up`/`down`) or jumps to the page extreme (`top`/`bottom`), then returns a fresh snapshot — useful to surface lazily-loaded content.
### `browser_back` / `browser_forward`
No parameters. Navigate one entry in browser history and return a fresh snapshot. Errors if there is no entry in that direction.
### `browser_get_text`
```ts
{
text_budget?: number; // max chars (default 8000)
}
```
Returns the page's readable text (innerText), normalized and clamped — without the interactive-element list.
### `browser_screenshot`
```ts
{
full_page?: boolean; // capture the whole scrollable page (default false = viewport)
}
```
Returns a PNG as MCP image content. Prefer `browser_snapshot` for *acting* on the page; use a screenshot when you need to *see* pixels (layout, charts, visual verification).
## How a typical session looks
```
browser_navigate { url: "https://news.ycombinator.com" }
-> snapshot with [e1] link "Hacker News", [e12] link "Show HN: ...", ...
browser_click { ref: "e12" }
-> fresh snapshot of the linked story
browser_back {}
-> back to the front page (refs renumbered)
browser_type { ref: "e3", text: "playwright", submit: true } // search box
-> fresh snapshot of results
```
## Development
```bash
npm install
npx playwright install chromium # one-time, for live-browser usage
npm run build
npm test # vitest (pure snapshot logic + --version; no browser needed)
npm run lint # biome
npm run typecheck
```
The vitest suite exercises the token-shaping logic (ref numbering, element-line rendering, text normalization + clamping, full snapshot layout) without launching Chromium — the heavy browser binary is never required to verify the part of the code where the real complexity lives.
## Release
This repo follows the YawLabs "CI trim" convention: no `.github/workflows/release.yml`. Releases ship locally:
```bash
npm login --auth-type=web # once, in your terminal (WebAuthn)
bash release.sh 0.2.0 # lint, test, build, bump, tag, publish, GitHub + MCP Registry release
```
`release.sh` is idempotent — re-running with the same version skips completed steps.
## License
MIT © Yaw Labs
## Links
- npm: https://www.npmjs.com/package/@yawlabs/vew-mcp
- issues: https://github.com/YawLabs/vew-mcp/issues
- Yaw Labs: https://vew.sh
