Content
# Browser MCP App
An MCP App that drives a real Chromium browser with Playwright and renders a live,
clickable view of the page inside an MCP host such as [Archestra]. The agent can browse
for you, and you can take over in the panel — click, type, scroll, navigate.
## How it works
Browser tools (`browser_navigate`, `browser_click`, `browser_type`, `browser_press`,
`browser_scroll`, `browser_back`/`forward`/`reload`, `browser_read_page`) drive one
shared Playwright page. The UI panel polls an app-only `browser_screenshot` tool (~1/s),
maps your clicks back to viewport pixels, and forwards your keystrokes — so the model
and you drive the same page.
## Setup
```bash
npm install
npm run browsers # one-time: download Chromium
npm run build # bundle the UI into dist/mcp-app.html
```
## Run
```bash
npm run serve # HTTP transport on :3001 (npm run dev = watch mode)
npm run serve:stdio # stdio transport
```
To use it from an MCP host (e.g. Archestra), build first and point the host's MCP config
at the stdio entry:
```json
{
"mcpServers": {
"browser": {
"command": "npx",
"args": ["-y", "tsx", "/absolute/path/to/browser-mcp-app/main.ts", "--stdio"]
}
}
}
```
## Configuration
| Env var | Default | Meaning |
| --- | --- | --- |
| `HEADLESS` | unset → headed | `1`/`true` runs Chromium headless. |
| `PORT` | `3001` | HTTP port. |
| `SCREENSHOT_QUALITY` | `60` | JPEG quality for the live view. |
## Development
Built with the **`create-mcp-app`** Agent Skill, which covers the MCP Apps SDK patterns
used here (tool + UI-resource registration, app lifecycle, host context, polling). Use
it when extending the server — invoke `/create-mcp-app`.
## Notes
- One shared browser page; actions are serialized so calls don't race.
- The live view is a screenshot stream — page pixels never go to the model; only
`browser_read_page` returns text, on request.
- It's a real browser: it can log in and submit forms. Don't point it at sites where an
unintended click would be costly.
[Archestra]: https://archestra.ai
[Playwright]: https://playwright.dev
