browser-agent
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
browser-agent
A browser the people on your team and the coding agents they use can share. Playwright drives a real Chromium session. The CLI and the MCP server talk to the same long-lived process, and every action comes back with an accessibility snapshot, a ref such as e3, and a clear success or failure.
Agents stop guessing CSS. A duplicate name is refused, with the candidate refs listed, before anything is clicked. A JavaScript dialog returns immediately instead of freezing the next tool call.
The pictures are one real session against examples/harbor. The snapshot on the right of the first row took 54ms. The click that opened the board took 119ms. Those times are from this run, after the browser was already open. They are not a benchmark.
What you can do
One session can cover the whole path a person would take through a web app.
Open a URL, a host (
example.com,localhost:3000), or a local HTML file. Go back, forward, and reload.Read the page as an accessibility tree, compact or full, and act on refs.
Click, double-click, right-click, hover, scroll, and press keys.
Fill fields. Password values are masked in the output. Type slowly when a page only listens to real keystrokes.
Choose a select option, and set files on an upload input.
Wait for text, for text to disappear, for a URL glob, a load state, a CSS selector, an element, or a JavaScript condition.
Take a viewport screenshot, a full-page screenshot, or a screenshot of one element. MCP returns the PNG to the model.
Run JavaScript in the page, or against one element.
Pull visible text, HTML, links, or a form summary.
Handle
alert,confirm,prompt, andbeforeunloadwithout deadlocking the agent.List, open, select, and close tabs. Popups are reported and are not stolen automatically.
List, set, and clear cookies. Read and write
localStorageandsessionStorage.Save downloads and list the files.
Watch console messages and recent network requests. Abort or fulfill requests that match a URL glob.
Run headless, or show the window. Use Playwright's Chromium, installed Chrome, or Edge, including beta, dev, and canary channels.
Reuse a Chrome profile, send traffic through a proxy, set the viewport and user agent, and record a WebM of the session.
Keep the browser alive between shell commands and between MCP tool calls. Name a session so an agent does not take the browser you are using.
Print human output, or
--jsonfor scripts. Talk to the same browser from Cursor, Claude Code, Claude Desktop, or any MCP client.
Related MCP server: Playwright MCP
Time it gives back
The expensive part of browser work for an agent is not the click. It is the turns spent guessing a selector, clicking the wrong Save, or waiting on an alert that never returns. browser-agent is built so that turn ends on the first correct ref.
These are working-time estimates for a developer who already knows the app. They are not a customer study.
Job | Without a shared agent browser | With browser-agent |
Confirm sign-in still reaches the next screen | 20–40 minutes the first time you write and maintain a Playwright script, or a manual pass on every change | The Harbor Desk path below: navigate, snapshot, type, click. About a minute, then the same commands after the next edit |
Let a coding agent see the UI it just changed | Paste screenshots by hand, or watch it retry selectors for several model calls | One MCP server. Each action returns the new snapshot |
Stop a wrong click on a repeated label | The first match is clicked, then you debug the damage | The action fails, lists every match, and clicks nothing |
Keep a logged-in browser between commands | Every script launches a fresh browser and logs in again | The daemon stays up. Later actions in the Harbor run were 50–120ms |
Show a teammate what happened | A separate screen recording, plus a verbal retelling |
|
Point Cursor, Claude Code, and a shell script at one browser | Three tools, three setups, three kinds of flake | One daemon, one session name, one result shape |
For a business, the saving shows up as fewer broken agent loops and less time rebuilding the same smoke check. A team that asks an agent to verify UI several times a day stops paying for the turns that used to be selector retries. The same commands run in a terminal, in CI, and inside the editor.
Quick start
Node.js 20 or newer.
npm install
npx playwright install chromium
npm run build
node dist/cli.js doctor
node dist/cli.js navigate https://example.com
node dist/cli.js snapshot --compact
node dist/cli.js closeAfter the package is published:
npm install -g browser-agent
browser-agent install
browser-agent navigate https://example.com
browser-agent snapshot --compact
browser-agent closebrowser-agent install downloads the Chromium build that matches this Playwright version. A single-file binary is not shipped. The browser is the large part, and it has to match the library.
On a machine where Chromium's sandbox cannot start, the daemon retries once with --no-sandbox. Set BROWSER_AGENT_NO_SANDBOX=1, or pass --arg --no-sandbox, to skip the first attempt.
Harbor Desk, end to end
The example is a one-file desk for a pier office. Serve it, then drive it.
python3 -m http.server 4173 --bind 127.0.0.1 --directory examples/harborbrowser-agent navigate http://127.0.0.1:4173/
browser-agent snapshot --compact
browser-agent type "Work email" ada@harbor.example
browser-agent type Password tide-0540
browser-agent click "Sign in"
browser-agent screenshot -o board.png
browser-agent closeThe password is masked in the observation and in the snapshot. The email stays visible because it is not a password field.
With no command in a terminal, browser-agent opens an interactive session:
browser-agent 0.1.0
Type a command, help, or exit.
› navigate http://127.0.0.1:4173/
› click "Sign in"
› exithelp lists the commands. exit leaves the prompt and leaves the browser running until close.
How an agent should work
browser_navigateto open the page.Read the snapshot. Use a ref such as
e3.browser_click,browser_type, or another action with that ref.If the result contains
pendingDialog, callbrowser_dialogbefore anything else.browser_screenshotwhen the pixels matter.browser_closewhen the task is done.
Refs last until the next navigation or snapshot. A click, a type, and the other mutations return a fresh compact snapshot, so the next action can use the new refs immediately. An explicit snapshot defaults to the full tree. Pass mode: "compact" when you only want controls and headings.
Set BROWSER_AGENT_SESSION=agent in the MCP config. The default session name is default. Sharing that name means the agent and your terminal are driving one window.
A prompt that produces a reliable run:
Open http://127.0.0.1:4173/, sign in with the pier office account, and confirm the morning board lists MV Calder. Use browser-agent. Do not guess selectors. If a dialog appears, handle it before the next action. If a name matches more than one element, use the ref from the error.
When a name is not unique
"Save" matched two buttons. Nothing was clicked. The hint points at a ref. click e2 is the next command, after you decide which Save you meant. The same rule applies to typing, hovering, and selecting.
CLI
Global flags can sit before or after the command.
Flag | Meaning |
| Print the structured result. |
| Named browser. Default |
| Show or hide the window. Headless is the default. |
| Chrome user-data directory. Close Chrome first if it already has that directory open. |
|
|
| Proxy server, for example |
| Proxy credentials. The password is part of the session identity. |
| Viewport, for example |
| Override the user agent. |
| A specific Chromium binary. |
| Record a WebM. The path is printed when the session closes. |
| Action timeout for this command. Default 15000. |
| Quit after inactivity. Default 1800. |
| Reject invalid TLS certificates. Invalid certificates are accepted by default. |
| Extra Chromium argument. Repeat it. |
| Skip the automatic snapshot. |
Launch flags are part of the session identity. Passing a different --headed, profile, proxy, viewport, or video setting against a running session returns SESSION_CONFIG_MISMATCH instead of quietly driving the wrong browser. A command that does not pass launch flags attaches to the session that is already running.
Commands
Command | What it does |
| Start the browser and leave it running. |
| Show the session. |
| Close the browser. |
| Open a URL. |
| History. |
| Accessibility tree. |
| Click. |
| Fill a field. |
|
|
| Hover. |
| Choose an option by label or value. |
| Set files on an input. The files must exist on the machine running the browser. |
|
|
| PNG. |
| JavaScript in the page. |
|
|
| See the flags below. |
|
|
| Close the open dialog. |
|
|
|
|
| List files saved this session. |
|
|
|
|
| MCP server on stdio. |
| Print an MCP config. |
| Download Playwright's Chromium. |
| Check Node, Playwright, and Chromium. |
| Interactive mode. This is also the default in a terminal. |
wait flags: --text, --text-gone, --url <glob>, --load <state>, --selector <css>, --target, --state visible\|hidden\|attached\|detached, --fn <expression>, --time <ms> (at most 10000). Prefer text, URL, or a load state over a fixed sleep.
networkidle is available and is a poor default. Pages with analytics or long-polling often never go idle. domcontentloaded is the default for navigation.
Targets
Form | Example | When to use it |
Snapshot ref |
| Default. Valid for the current snapshot. |
Accessible name |
| When that name is unique. |
Role phrase |
| Role plus name. |
Label |
| A labeled control. |
Placeholder |
| Placeholder text. |
Role query |
| When the name alone is shared. |
Text |
| Visible text. |
Test id |
|
|
CSS |
| Last resort. |
XPath |
| Last resort. |
A phrase like "Login button" is a button named Login. "Work email" matches a textbox, searchbox, or combobox with that name. Matching is exact, then case-insensitive, then a substring when the query is at least 3 characters. Interactive controls and headings are preferred.
Refs remember the role, the accessible name, which occurrence it was, and the Chrome accessibility node. A click resolves that node and then performs a real Playwright click. If the node is gone, the role and name are tried. If several elements still match, the action is AMBIGUOUS_TARGET.
MCP
The server speaks stdio and starts the same daemon the CLI uses.
browser-agent init cursor
browser-agent init claude-desktop
browser-agent init claude-codeCursor (.cursor/mcp.json or ~/.cursor/mcp.json), Claude Desktop (claude_desktop_config.json), and Claude Code (.mcp.json):
{
"mcpServers": {
"browser-agent": {
"command": "npx",
"args": ["-y", "browser-agent", "mcp"],
"env": { "BROWSER_AGENT_SESSION": "agent" }
}
}
}Claude Code can also add it with claude mcp add browser-agent -- npx -y browser-agent mcp. From a checkout, point command at node and args at dist/cli.js plus mcp.
The server registers a browser-task prompt that describes the ref loop for the model.
Tools
Every tool returns text plus structured content. A failure sets the MCP error flag. browser_screenshot also returns the PNG.
Tool | Parameters |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Session state. |
| Close the browser. |
snapshot on an action is true, "compact", "full", or false. timeout is milliseconds, at most 180000.
A successful result:
{
"ok": true,
"action": "click",
"url": "http://127.0.0.1:4173/",
"title": "Harbor Desk",
"observation": "Clicked button \"Sign in\" [ref=e3].",
"snapshot": "- button \"New berth\" [ref=e1]\n- heading \"MV Calder\" [ref=e2] [level=2]"
}Dialogs
An alert or confirm opened by a click does not block the tool. The response is ok: true with pendingDialog. The next action returns DIALOG_OPEN until browser_dialog accepts or dismisses it. A serial agent can handle the dialog instead of retrying a click that is already waiting.
browser-agent dialog accept
browser-agent dialog dismiss
browser-agent dialog accept --prompt "yes"Two workflows
Shell, for a smoke check you can put in CI:
browser-agent --session ci navigate "$BASE_URL/login"
browser-agent --session ci type "Work email" "$EMAIL"
browser-agent --session ci type Password "$PASSWORD"
browser-agent --session ci click "Sign in"
browser-agent --session ci wait --text "MV Calder"
browser-agent --session ci screenshot --full -o board.png
browser-agent --session ci closeMCP, for an agent editing the app:
browser_navigate { "url": "http://127.0.0.1:4173/" }
browser_type { "target": "Work email", "text": "ada@harbor.example" }
browser_type { "target": "Password", "text": "tide-0540" }
browser_click { "target": "e3" }
browser_wait { "text": "MV Calder" }
browser_screenshot { "fullPage": false }Other useful sessions:
browser-agent --headed navigate http://localhost:3000
browser-agent --session qa --profile ~/.config/google-chrome --channel chrome navigate https://mail.example
browser-agent --proxy http://127.0.0.1:8080 navigate https://example.com
browser-agent network route "**/analytics/**"
browser-agent network route "**/api/user" --fulfill --status 200 --body '{"name":"Ada"}' --content-type application/json
browser-agent cookies set --name session --value abc
browser-agent storage set theme dark
browser-agent tabs new https://example.com/docs
browser-agent tabs select 0
browser-agent eval "document.title"
browser-agent extract forms
browser-agent --video navigate https://example.com
browser-agent close--profile uses a real browser profile, including its cookies. Prefer a dedicated profile for agents.
Architecture
CLI ──┐
├── HTTP 127.0.0.1 ── daemon ── Playwright ── Chromium
MCP ──┘ bearer tokenEach session lives in ~/.browser-agent/sessions/<name>/. BROWSER_AGENT_DATA_DIR overrides the root.
File | Role |
| Port, token, pid, and the public launch config. Mode |
| Launch config, written for the new process and deleted after it is read. |
| Daemon stderr. |
| PNGs, unless you pass a path. |
| Files saved from the page. |
The daemon binds 127.0.0.1 on a random port. Clients send Authorization: Bearer … and POST /action. Actions run one at a time, so two overlapping clicks cannot race. Playwright is imported only when a browser starts, so browser-agent --help stays cheap.
Snapshots come from Chrome's accessibility tree. Hidden subtrees are skipped. Password-like values are masked. Compact mode lists controls and headings. Full mode adds structure and static text that is not already the parent's name.
Configuration
Variable | Default | Meaning |
|
| Session name. |
|
| Session root. |
| off | Show the window. |
| Playwright Chromium |
|
| ephemeral profile | User-data directory. |
| Proxy URL. | |
| Proxy user. | |
| Proxy password. Included in the session identity. | |
|
|
|
| browser default | User agent. |
| Chromium binary. | |
| Extra Chromium arguments, comma-separated. | |
| off | Add |
| off | Record WebM. |
|
| Action timeout, milliseconds. |
|
| Navigation timeout, milliseconds. |
|
| Inactivity limit, seconds. |
|
| Accept invalid TLS. |
| off | Client debug logs on stderr. MCP stdout stays JSON-RPC. |
Errors
Failures carry code, message, and usually hint.
Code | Meaning |
| More than one element matched. Nothing was activated. |
| No element matched. |
| That ref is not in the latest snapshot. |
| The ref's node is gone. Take a new snapshot. |
| The target string could not be parsed. |
| Accept or dismiss the dialog before the next action. |
| The action or wait exceeded its limit. |
| DNS, connection, or proxy failure. |
| The URL scheme is not |
| The browser has no page. Retry, and the session relaunches. |
| Run |
| The daemon did not become ready. See |
| The browser exited during the action. |
| Another process has that user-data directory. |
| This command asked for different launch options than the running session. |
| The process is alive and not answering. Close the session and retry. |
| An upload path is missing. |
| The page rejected the expression. |
|
|
| A flag or parameter was missing or out of range. |
Comparison
browser-agent | Playwright MCP | agent-browser | chrome-devtools-mcp | |
Built for | A shell and a coding agent on one browser | MCP clients | Agent CLIs | DevTools-level control |
Interface | CLI and MCP | MCP | CLI daemon | MCP |
Engine | Playwright | Playwright | Chromium automation | Chrome DevTools |
Targeting | Accessibility refs. Shared names fail closed. | Accessibility refs | Snapshot refs | Snapshot uids |
Session | Stays up between shell commands and tool calls | The MCP server's lifetime | CLI daemon | A connected Chrome |
Dialogs | The action returns with | Depends on the tool | Depends on the tool | DevTools protocol |
Also included | Cookies, storage, downloads, route abort and fulfill, video, profiles, proxy | Browser tools | Agent CLI | Network and debugging |
Playwright MCP is the right choice when you want Microsoft's MCP server and nothing else. agent-browser is a strong CLI. chrome-devtools-mcp is the right choice when you want the DevTools protocol itself. browser-agent is the one process a human shell and an MCP client both drive, with results a serial agent can recover from.
Security
The daemon listens on loopback only. session.json holds the bearer token and is mode 0600.
browser_evaluate runs in the page, not in the daemon. It can read that page's DOM, cookies, and storage. Treat page content as untrusted, and do not evaluate instructions that came from the page.
--profile uses a real browser profile. That includes logged-in sessions. Prefer a dedicated profile for agents.
There is no stealth or evasion mode. The browser is a normal Playwright Chromium for local development, QA, and agent verification.
Troubleshooting
browser-agent doctor checks Node, Playwright, and the Chromium binary.
Symptom | What to do |
|
|
Sandbox error on launch |
|
| Close the other Chrome using that directory, or omit |
|
|
| Close that session and retry. The log is |
|
|
| Click the ref from the hint |
|
|
The page never finishes | Stay on |
MCP and the terminal fight over one window | Give the MCP config |
Debug logging for the client is BROWSER_AGENT_DEBUG=1. It writes to stderr so an MCP session does not corrupt stdout.
Development
npm install
npx playwright install chromium
npm test
npm run typecheck
npm run dev -- navigate https://example.comTests use Vitest. They cover the snapshot formatter, target parsing, CLI help, an in-process browser session, the session daemon, and an MCP browser_navigate call. CI installs Chromium and runs typecheck, tests, and node dist/cli.js --help.
The library entry is browser-agent (dist/index.js). It exports the controller, runAction, snapshot helpers, and config helpers. The MCP server stays out of that entry so a library import does not load the stdio server.
License
MIT. See LICENSE.
Let's connect and collaborate
I am open to Senior Remote Full-Stack Roles, AI Platform Architecture Contracts, and Enterprise Technical Advisory.
Timezone: UTC+6 (Dhaka / Rangpur, Bangladesh). Flexible overlap with US, UK, and European business hours.
Delivery mode: async-ready, Slack, Discord, Jira, GitHub, and production-first accountability.
Channel | Address | Action |
Primary portfolio | ||
Packagist packages | ||
GitHub | ||
X | ||
YouTube |
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Related MCP Connectors
Control a real browser from AI agents: navigate, click, type, screenshot, read the page.
Give AI agents a real cloud Chrome: open sessions, navigate, read pages, click, type and screenshot.
Playwright browser automation — navigate, click, fill forms, extract, screenshot — 17 agent tools.
Let your AI agent operate any website through a real, logged-in browser session.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceEnables browser automation and web interaction through structured accessibility snapshots using Playwright. Supports clicking, typing, navigation, form filling, and other web actions without requiring screenshots or vision models.10,908,336 npm-
- AlicenseNot gradedqualityCmaintenanceProvides browser automation capabilities using Playwright, allowing LLMs to interact with web pages through structured accessibility snapshots without needing screenshots or vision models.2Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control a local browser via Playwright's accessibility tree, allowing automated web interactions and testing through natural language commands.MIT
- AlicenseBqualityCmaintenanceEnables AI assistants to control a real Chromium browser through Playwright, allowing them to navigate pages, click elements, fill forms, extract text or HTML, and capture screenshots in a persistent session.6ISC