opencode-browser-control

Playwright-powered browser automation MCP server for OpenCode. Controls Chrome/Edge with ARIA accessibility snapshots and numbered element refs — no CSS selectors, no guessing.

Quick Start

1. Install dependencies

npm install -g playwright-core
npx playwright install chromium

2. Configure OpenCode

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "browser-control": {
      "type": "local",
      "command": ["npx", "-y", "opencode-browser-control"],
      "enabled": true
    }
  }
}

3. Restart OpenCode

The browser, browser_snapshot, browser_click, and browser_type tools will be available.

Tools

`browser(action, ...)` — Multiplexed Tool

Action	Description	Key Params
`start`	Launch browser	`headed` (default: true)
`stop`	Close browser	—
`navigate`	Open URL	`url`, `page_id`
`snapshot`	ARIA snapshot with element refs	`page_id`
`click`	Click element by ref	`ref` (e.g. `e42`)
`type`	Type into input by ref	`ref`, `text`, `submit`
`evaluate`	Execute JavaScript	`code`
`screenshot`	Full-page screenshot	`page_id`
`tabs`	List all tabs	—
`close_tab`	Close a tab	`page_id`
`back` / `forward`	Navigate history	—

Shortcut Tools

Tool	Description
`browser_snapshot`	Get ARIA snapshot with `e1, e2, e3...` refs
`browser_click(ref)`	Click element by snapshot ref
`browser_type(ref, text)`	Type into element by snapshot ref

Typical Workflow

1. browser(action="navigate", url="https://example.com")
2. browser_snapshot()            → returns e1: button "Login", e2: textbox "Email", ...
3. browser_type(ref="e2", text="[email protected]")
4. browser_click(ref="e1")
5. browser_snapshot()            → verify result

Browser Support

Auto-detects in priority order:

OS	Priority
Windows	Edge → Chrome
macOS	Chrome → Edge
Linux	Chrome → Edge → Chromium

Falls back to Playwright's bundled Chromium if no system browser is found.

Persistent Profile

A persistent profile is stored at ~/.opencode/browser-profile/{browser}/. Login state, cookies, and local storage persist across sessions. The profile is isolated from your normal browser — it won't interfere with your daily browsing.

Architecture

OpenCode ──MCP(stdio)──▶ index.mjs ──Playwright──▶ Edge/Chrome

Single-file Node.js MCP server. No HTTP middle layer, no browser extensions, no CDP port configuration. Playwright manages the browser lifecycle automatically.

Troubleshooting

Problem	Solution
"playwright-core not found"	`npm install -g playwright-core`
Browser doesn't launch	Install Chromium: `npx playwright install chromium`
SPA navigation breaks refs	Re-run `browser_snapshot()` after navigation — refs are invalidated on page change
Elements not clickable	The snapshot only finds visible elements. Use `browser_evaluate` to scroll or interact with hidden elements

License

MIT

opencode-browser-control