Agent Browser MCP

MCP server for agent-browser — a fast, Rust-based browser automation CLI built on Playwright.

This package exposes 100 tools across 18 categories, enabling any MCP-compatible AI client to automate web browsers: navigate pages, interact with elements, capture screenshots, intercept network traffic, manage authentication, record sessions, and more.

Requirements

• Node.js >= 20.0.0
• agent-browser 0.26.0（其余版本未做测试）

Install agent-browser:

# macOS / Linux
curl -fsSL https://agent-browser.dev/install.sh | bash

# npm
npm install -g agent-browser

Verify installation:

agent-browser --version

Quick Start

npx (no install)

npx @rabbitai-lab/agent-browser-mcp

Global install

npm install -g @rabbitai-lab/agent-browser-mcp
agent-browser-mcp

The server starts on http://localhost:12347/mcp by default. Use --port <number> or the PORT environment variable to change it.

MCP Client Configuration

Add to your MCP client config file (e.g. .mcp.json or claude_desktop_config.json):

{
  "mcpServers": {
    "agent-browser": {
      "command": "npx",
      "args": ["@rabbitai-lab/agent-browser-mcp"]
    }
  }
}

Or connect via URL (Streamable HTTP transport):

{
  "mcpServers": {
    "agent-browser": {
      "url": "http://localhost:12347/mcp"
    }
  }
}

Tools Reference

Navigation

| Tool | Description | |------|-------------| | open | Navigate to a URL | | back | Go back to the previous page | | forward | Go forward to the next page | | reload | Reload the current page | | close | Close the browser session | | connect | Connect to a browser via CDP |

Interaction

| Tool | Description | |------|-------------| | click | Click an element by selector or @ref | | dblclick | Double-click an element | | type | Type text into an element (appends) | | fill | Clear and fill an element with text | | press | Press a keyboard key | | hover | Hover over an element | | focus | Focus an element | | check | Check a checkbox | | uncheck | Uncheck a checkbox | | select | Select dropdown option(s) | | drag | Drag and drop | | upload | Upload file(s) to an element | | download | Download a file by clicking an element | | scroll | Scroll the page or a scrollable container | | scroll_into_view | Scroll an element into view | | wait | Wait for an element, timeout, or condition |

Query

| Tool | Description | |------|-------------| | snapshot | Capture accessibility tree with element refs | | get | Get element information (text, html, value, attr, title, URL, etc.) | | is | Check element state (visible, enabled, checked) | | find | Find elements by locator and perform an action | | eval | Run JavaScript in the browser page |

Visual

| Tool | Description | |------|-------------| | screenshot | Take a screenshot of the current page | | pdf | Save the current page as PDF | | diff_snapshot | Compare current accessibility snapshot vs last snapshot | | diff_screenshot | Compare current screenshot vs baseline image | | diff_url | Compare two URLs side by side | | highlight | Highlight an element on the page |

Tabs & Frames

| Tool | Description | |------|-------------| | tab_list | List all browser tabs | | tab_new | Open a new tab | | tab_close | Close a tab | | tab_switch | Switch to a tab by reference or label | | frame | Switch frame context (iframe or main) | | window_new | Open a new browser window |

Network

| Tool | Description | |------|-------------| | network_route | Intercept network requests by URL pattern | | network_unroute | Remove a network route | | network_requests | List network requests | | network_request_detail | Get full details of a network request | | network_har | Start or stop HAR recording |

Storage

| Tool | Description | |------|-------------| | cookies_get | Get all cookies | | cookies_set | Set a cookie | | cookies_clear | Clear all cookies | | storage_get | Get web storage value(s) | | storage_set | Set a web storage value | | storage_clear | Clear web storage |

Browser Settings

| Tool | Description | |------|-------------| | set_viewport | Set browser viewport size | | set_device | Emulate a device | | set_geolocation | Set geolocation | | set_offline | Toggle offline mode | | set_headers | Set HTTP headers | | set_credentials | Set HTTP authentication credentials | | set_color_scheme | Set color scheme preference |

Keyboard

| Tool | Description | |------|-------------| | keyboard_type | Type text with real keystrokes (no selector needed) | | keyboard_insert | Insert text without key events | | keydown | Press and hold a key | | keyup | Release a previously held key |

Mouse

| Tool | Description | |------|-------------| | mouse_move | Move mouse to coordinates | | mouse_down | Press a mouse button | | mouse_up | Release a mouse button | | mouse_wheel | Scroll the mouse wheel |

Auth & State

| Tool | Description | |------|-------------| | auth_save | Save an authentication profile | | auth_login | Login using a saved auth profile | | auth_list | List saved auth profiles | | auth_show | Show auth profile metadata | | auth_delete | Delete a saved auth profile | | state_save | Save browser auth state to a file | | state_load | Load browser auth state from a file | | state_list | List saved state files | | state_show | Show state file summary | | state_rename | Rename a state file | | state_clear | Clear saved states | | state_clean | Delete old state files |

Dialog & Confirmation

| Tool | Description | |------|-------------| | dialog_accept | Accept a dialog (alert/confirm/prompt) | | dialog_dismiss | Dismiss a dialog | | dialog_status | Check if a dialog is currently open | | confirm | Approve a pending confirmation action | | deny | Deny a pending confirmation action |

Debug & Recording

| Tool | Description | |------|-------------| | console | View console logs | | errors | View page errors | | trace | Record Chrome DevTools trace | | profiler | Record Chrome DevTools profile | | record | Record browser session as video (WebM) | | clipboard | Read or write the clipboard | | inspect | Open Chrome DevTools for the active page |

Sessions & Dashboard

| Tool | Description | |------|-------------| | session_list | List active browser sessions | | stream_enable | Start runtime WebSocket streaming | | stream_disable | Stop runtime WebSocket streaming | | stream_status | Show streaming status and active port | | dashboard_start | Start the observability dashboard server | | dashboard_stop | Stop the dashboard server |

React DevTools

| Tool | Description | |------|-------------| | react_tree | Show full React component tree | | react_inspect | Inspect a single React component by fiber ID | | react_renders | Start or stop React fiber render recording | | react_suspense | List React Suspense boundaries |

Batch & Misc

| Tool | Description | |------|-------------| | batch | Execute multiple browser commands sequentially | | doctor | Diagnose agent-browser installation and configuration | | chat | Send a natural language instruction to the AI agent | | pushstate | SPA client-side navigation via history.pushState | | profiles | List available Chrome profiles | | session | Show current session name | | vitals | Measure Web Vitals (LCP / CLS / TTFB / FCP / INP) | | addinitscript | Register an init script at runtime | | removeinitscript | Remove a previously registered init script |

Development

# Install dependencies
npm install

# Build
npm run build

# Dev mode (hot reload)
npm run dev

# Type check
npm run typecheck

# Unit tests
npm run test:unit

# E2E tests (requires agent-browser running)
npm run test:e2e

Architecture

src/
├── index.ts          # Entry point, CLI argument parsing
├── server.ts         # HTTP server + MCP Streamable HTTP transport
├── executor.ts       # CLI subprocess executor (agent-browser)
├── utils.ts          # Shell escaping, arg builders
└── tools/
    ├── index.ts      # Tool registration hub
    ├── navigation.ts
    ├── interaction.ts
    ├── query.ts
    ├── visual.ts
    ├── tabs.ts
    ├── network.ts
    ├── storage.ts
    ├── browser-settings.ts
    ├── keyboard.ts
    ├── mouse.ts
    ├── auth.ts
    ├── state.ts
    ├── dialog.ts
    ├── confirmation.ts
    ├── debug.ts
    ├── sessions.ts
    ├── dashboard.ts
    ├── react.ts
    ├── batch.ts
    └── misc.ts

Each tool module registers MCP tools via server.tool(name, schema, handler). The handler constructs a CLI command string and delegates execution to CliExecutor, which spawns agent-browser as a subprocess.

License

Apache-2.0