mcp

@browseragentprotocol/mcp

MCP (Model Context Protocol) server for Browser Agent Protocol. Gives any MCP-compatible AI agent full browser control.

Installation

One command — standalone mode

npx @browseragentprotocol/mcp

This auto-starts a BAP Playwright server and exposes browser tools over MCP stdio. No separate server process needed.

Add to an MCP client

Claude Code:

claude mcp add --transport stdio bap-browser -- npx -y @browseragentprotocol/mcp

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "bap-browser": {
      "command": "npx",
      "args": ["-y", "@browseragentprotocol/mcp"]
    }
  }
}

Codex CLI:

codex mcp add bap-browser -- npx -y @browseragentprotocol/mcp

Codex Desktop — add to ~/.codex/config.toml:

[mcp_servers.bap-browser]
command = "npx"
args = ["-y", "@browseragentprotocol/mcp"]

Connect to an existing BAP server

If you already have a BAP Playwright server running, pass --url to skip auto-start:

npx @browseragentprotocol/mcp --url ws://localhost:9222

How It Works

┌─────────────┐     MCP      ┌─────────────┐    BAP     ┌─────────────┐
│  AI Agent   │ ──────────── │  BAP MCP    │ ────────── │ BAP Server  │
│  (any MCP   │   (stdio)    │   Server    │ (WebSocket)│ (Playwright)│
│   client)   │              │             │            │             │
└─────────────┘              └─────────────┘            └─────────────┘
                                                              │
                                                              ▼
                                                        ┌─────────────┐
                                                        │   Browser   │
                                                        └─────────────┘

1. AI agent sends tool calls via MCP (stdio transport)
2. This package translates them to BAP protocol
3. BAP server controls the browser via Playwright
4. Results flow back to the agent

Event Streaming

Browser console errors and 4xx/5xx network responses are automatically forwarded to connected MCP clients as notifications/message log entries. No configuration needed.

Available Tools

Navigation

Tool	Description
navigate	Navigate to a URL. Supports fused observe parameter to get page observation in one roundtrip
go_back	Navigate back in browser history
go_forward	Navigate forward in browser history
reload	Reload the current page

Element Interaction

Tool	Description
click	Click an element using semantic selectors
type	Type text character by character (first clicks element)
fill	Fill a form field (clears existing content first)
press	Press keyboard keys (Enter, Tab, shortcuts)
select	Select an option from a dropdown
scroll	Scroll the page or a specific element
hover	Hover over an element

Observation

Tool	Description
screenshot	Take a screenshot of the page
accessibility	Get the full accessibility tree
aria_snapshot	Token-efficient YAML accessibility snapshot (~80% fewer tokens)
content	Get page text content as text or markdown
element	Query element properties (exists, visible, enabled)

Page Management

Tool	Description
pages	List all open pages/tabs
activate_page	Switch to a different page/tab
close_page	Close the current page/tab

AI Agent Methods

Tool	Description
observe	AI-optimized page observation with interactive elements and stable refs. Supports incremental (diff mode) and responseTier (full/interactive/minimal)
act	Execute a sequence of browser actions in a single call. Supports fused postObserve to get observation in one roundtrip
extract	Extract structured data from the page using schema and CSS heuristics

Selector Formats

Tools that accept a selector parameter support these formats:

role:button:Submit        # ARIA role + accessible name (recommended)
text:Sign in              # Visible text content
label:Email address       # Associated label
testid:submit-button      # data-testid attribute
ref:@submitBtn            # Stable element reference from observe
css:.btn-primary          # CSS selector (fallback)
xpath://button[@type]     # XPath selector (fallback)

CLI Options

Options:
  -b, --browser <name>        Browser: chrome (default), chromium, firefox, webkit, edge
  -u, --url <url>             Connect to existing BAP server (skips auto-start)
  -p, --port <number>         Port for auto-started server (default: 9222)
  --headless                  Run browser headless (default: true)
  --no-headless               Visible browser window
  --allowed-domains <list>    Comma-separated list of allowed domains
  --slim                      Expose only 5 essential tools (navigate, observe, act, extract,
                              screenshot). Reduces tool definitions from ~4,200 to ~600 tokens
  --in-process                Run the Playwright server in-process instead of as a child process
  -v, --verbose               Enable verbose logging to stderr
  -h, --help                  Show help
  --version                   Show version

Programmatic Usage

import { BAPMCPServer } from "@browseragentprotocol/mcp";

const server = new BAPMCPServer({
  bapServerUrl: "ws://localhost:9222",
  name: "my-browser-server",
  verbose: true,
});

await server.run();

Requirements

• Node.js >= 20.0.0
• An MCP-compatible client

The BAP Playwright server is auto-started by default. To install Playwright browsers manually: npx playwright install chromium.

Troubleshooting

"Connection closed" on Windows?

On native Windows (not WSL), use the cmd /c wrapper:

{
  "mcpServers": {
    "bap-browser": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@browseragentprotocol/mcp"]
    }
  }
}

Server not starting?

Ensure Playwright browsers are installed:

npx playwright install chromium

License

Apache-2.0