mcp-agent-browser

MCP server for the agent-browser CLI.

Prerequisites

Install the Vercel agent-browser CLI: https://github.com/vercel-labs/agent-browser

Ensure Playwright browser binaries are installed:

agent-browser install

MCP install

pnpm install
pnpm build

From npm

npm install -g mcp-agent-browser

codex mcp add mcp-agent-browser

Configuration

• AGENT_BROWSER_BIN: Override the agent-browser CLI path.
• AGENT_BROWSER_MCP_LOG: Write JSONL logs for all tool calls.
• AGENT_BROWSER_MCP_TIMEOUT_MS: Per-command timeout in ms (default: 30000).

Smoke test (stdio)

npm run build
npm run smoke

The smoke test sends a correct MCP initialize request (including protocolVersion) and then lists tools.

Run

node dist/mcp.js

Run with npx

Once published:

npx mcp-agent-browser

Electron/CDP usage:

# Start Electron with a remote debugging port (example)
./YourElectronApp --remote-debugging-port=9222

# Connect once, then run commands
agent-browser connect 9222

# Or pass --cdp on each command
agent-browser --cdp 9222 snapshot

MCP usage with Electron/CDP:

{ "name": "browser.connect", "arguments": { "port": 9222, "session": "agent1" } }
{ "name": "browser.snapshot", "arguments": { "session": "agent1", "cdpPort": 9222 } }

MCP JSON-RPC example (stdio):

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "browser.connect", "arguments": { "port": 9222, "session": "agent1" } } }
{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "browser.snapshot", "arguments": { "session": "agent1", "cdpPort": 9222 } } }

MCP tool payloads (decoded from content.text):

{ "ok": true, "port": 9222 }

{
  "ok": true,
  "elements": [{ "ref": "e1", "role": "button", "name": "Submit", "selectorHint": "@e1" }],
  "raw": {
    "snapshot": "...",
    "refs": { "e1": { "role": "button", "name": "Submit" } }
  }
}

See docs/mcp-agent-browser.md for tool definitions, error handling, and configuration.