@codeinklingon/browser-mcp

vibecoded port of oh-my-pi's browser tool as an mcp server

MCP server for headless browser automation via Puppeteer. Drop-in replacement for @playwright/mcp with enhanced stealth anti-detection and Playwright-format ARIA snapshots.

Usage

Add to your opencode.json:

{
  "mcp": {
    "browser-mcp": {
      "type": "local",
      "command": ["npx", "-y", "@codeinklingon/browser-mcp"],
      "enabled": true
    }
  }
}

Or install the skill (registers the MCP server + loads AI guidance):

npx skills install @codeinklingon/browser-mcp

Or run directly:

npx @codeinklingon/browser-mcp

Tools

Tool	Description
browser_tab_open	Open a tab, optionally navigate to a URL
browser_tab_run	Execute JS in the tab — has full tab API in scope
browser_tab_close	Close the tab and release resources

The tab API

Every browser_tab_run call has tab, display, wait, assert in scope.

Navigation & Info

Method	Notes
tab.url()	Current URL (sync)
tab.title()	Page title
tab.goto(url, { waitUntil? })	'load', 'domcontentloaded', 'networkidle'
tab.waitForNavigation({ waitUntil?, timeout? })	Wait for next page load

Click & Input

Method	Notes
tab.click(selector)	CSS, text/, xpath/, aria-ref=
tab.type(selector, text)	Type into input
tab.fill(selector, value)	Clear then type
tab.press(key, { selector? })	'Enter', 'Escape', etc.
tab.hover(selector)
tab.select(selector, ...values)	<select> options
tab.drag(from, to)	Selector or { x, y } point
tab.uploadFile(selector, ...filePaths)	File input

Scrolling & Visibility

Method	Notes
tab.scroll(dx, dy)	Scroll by pixels
tab.scrollIntoView(selector)	Center element in viewport

Page State

Method	Notes
tab.observe()	Accessibility tree: { elements: [{ id, role, name, value, focused }] }
tab.ariaSnapshot()	Playwright-format YAML with [ref=eN] ids, [cursor=pointer] on clickables
tab.evaluate(fn, ...args)	Raw JS in page context
tab.extract(format?)	'markdown' / 'text' / omitted = HTML
tab.screenshot({ fullPage?, selector? })	Base64 PNG

Element Refs

Method	Notes
tab.id(n)	ElementHandleActions from observe() id
tab.ref("e5")	ElementHandleActions from ariaSnapshot() ref
tab.waitForSelector(...)	CSS, text, xpath, aria-ref
tab.waitForUrl(pattern, { timeout? })	String substring or RegExp
tab.waitForResponse(pattern, { timeout? })	String, RegExp, or function

ElementHandleActions: { click, type, fill, hover, focus, screenshot, evaluate, scrollIntoView }

Important

• display, wait, assert are bare globals — NOT tab.* methods
  • display(x) ✓ — tab.display(x) ✗
  • wait(2000) ✓ — tab.wait(2000) ✗
• Navigation invalidates refs — re-run ariaSnapshot() or observe() after goto()
• Single-expression code auto-returns its value (no explicit return needed)

Selector Syntax

Prefix	Example	Notes
(none)	'button.submit'	CSS selector
text/	'text/Sign in'	Visible text (retries 10x)
xpath/	'xpath//button'	XPath
aria-ref=	'aria-ref=e12'	Ref from ariaSnapshot()

Example

await tab.goto('https://example.com/login')
const snap = await tab.ariaSnapshot()
display(snap)
await tab.fill('aria-ref=e5', 'admin')
await tab.fill('aria-ref=e8', 'password')
await tab.click('aria-ref=e12')
await tab.waitForNavigation()
display(tab.url())
const screenshot = await tab.screenshot()
display(screenshot)

Install

# Quick start — installs the skill and registers the MCP server
npx skills install codeinklingon/browser-mcp

# Or manually add to opencode.json (see Usage above)

Build from source

npm install
npm run build

Publish:

npm publish

License

MIT