text-browser-agent

# text-browser-agent

让 AI 用纯文本看懂网页，浏览器自动化从此不烧视觉 token。

Windows browser automation bridge for AI agents. Drives real Chrome via Puppeteer/CDP with an agent-friendly API — AX-tree text snapshots, no vision tokens needed. Ships as both a CLI and a Model Context Protocol (MCP) server.

Why this exists

Browser automation for AI agents usually burns vision tokens on screenshots — expensive, slow, and error-prone. This tool takes a different route:

The accessibility (AX) tree is already text.

text-browser-agent converts any page into a plain-text snapshot via snapshotText(), so any cheap text model can "see" and drive a real Chrome browser. No images, no vision round-trips.

Related MCP server: web-ui-tester

Features

• AX-tree text snapshots — snapshotText() returns the page as structured text.

• Full interaction — click, fill, type, press keys, scroll, hover.

• Raw CDP — allowlisted cdp() for power users.

• MCP server — official @modelcontextprotocol/sdk, works with any MCP client.

• Headless or headed — --headless for automation, headed for human viewing.

• Persistent task spaces — real, saved task spaces (not stubs).

• Security-first — no shell execution, URL/SSRF allowlist, CDP allowlist, screenshot path sandbox. See SECURITY.md.

Installation

# from the project directory
npm install
npm link          # exposes the `text-browser-agent` CLI globally

Prerequisites:

• Node.js >= 22

• Chrome at C:\Program Files\Google\Chrome\Application\chrome.exe (override with CHROME_PATH). If the browser wasn't downloaded: npx puppeteer browsers install

Quick start

1. Environment check

text-browser-agent --doctor

2. Run a script (helpers injected)

@'
await openOrReuseTab("https://example.com")
console.log(await snapshotText())
'@ | text-browser-agent nodejs

Headless:

@'
await openOrReuseTab("https://example.com")
console.log(await snapshotText())
'@ | text-browser-agent nodejs --headless

3. MCP server — connect and go

The MCP server uses the official @modelcontextprotocol/sdk, so it works with any MCP client (Claude Code, Cursor, Cline, opencode, etc.) with zero custom glue.

text-browser-agent --mcp            # headed (visible Chrome)
text-browser-agent --mcp --headless # headless (recommended for automation)

Add it to your client's MCP config as a stdio server:

{
  "mcpServers": {
    "text-browser-agent": {
      "command": "text-browser-agent",
      "args": ["--mcp", "--headless"]
    }
  }
}

A ready-to-copy config lives in mcp.example.json.

Claude Code — add to .mcp.json (project) or ~/.claude.json (global):

{
  "mcpServers": {
    "text-browser-agent": {
      "command": "text-browser-agent",
      "args": ["--mcp", "--headless"]
    }
  }
}

Cursor — Settings → MCP → Add server, choose "command", enter text-browser-agent --mcp --headless.

opencode — add to opencode.json:

{
  "mcp": {
    "text-browser-agent": {
      "type": "local",
      "command": ["text-browser-agent", "--mcp", "--headless"]
    }
  }
}

The server exposes 26 tools: openOrReuseTab, listTabs, switchTab, closeTab, currentTab, gotoAndWait, pageInfo, snapshotText, captureScreenshot, click, doubleClick, hover, scrollBy, scrollToBottomUntil, fillInput, typeText, pressKey, js, cdp, serverFetch, browserFetch, and task-space management (useOrCreateTaskSpace, listTaskSpaces, newTaskSpace, completeTaskSpace, handOffTaskSpace).

API reference

Task spaces (persisted)

useOrCreateTaskSpace(name) · listTaskSpaces() · newTaskSpace(name) · switchTaskSpace(name) · claimTaskSpace(name) · completeTaskSpace(name) · handOffTaskSpace(name) · takeOverTaskSpace(name) · waitForAgentControl()

Tabs / navigation

openOrReuseTab(url, opts?) · listTabs() · switchTab(targetId) · closeTab(targetId) · currentTab() · gotoAndWait(url, opts?) · pageInfo()

Observation

snapshotText(opts?) · captureScreenshot(opts?) · cliLog(...) · drainEvents()

Mouse

click(sel, opts?) · doubleClick(sel) · hover(sel) · scrollBy(delta) · scrollToBottomUntil(pred, opts?) · scroll({dy})

Keyboard / input

typeText(text, opts?) · fillInput(sel, text) · pressKey(key)

CDP / JS / network

js(expression) · cdp(method, params?) · browserFetch(url) · serverFetch(url, opts?)

Environment variables

Security

This tool is default-deny: no shell execution, URL/SSRF allowlist, CDP method allowlist, and a screenshot path sandbox. It is a local tool and does not listen on any port. Read SECURITY.md for the full threat model.

License

MIT. Underlying puppeteer is Apache-2.0 (Copyright The Chromium Authors).

Contact

Questions, feedback, or collaboration? Reach out on WeChat:

WeChat: 1127765955

If you find this tool useful, a ⭐ on GitHub goes a long way. Thanks!