Skip to main content

​
BAP MCP Server

MCP (Model Context Protocol) server that gives any MCP-compatible AI agent full browser control. Translates MCP tool calls into BAP protocol commands, which drive a real browser via Playwright.

​
Architecture

+--------------+     MCP      +--------------+    BAP     +--------------+
|  AI Agent    | ------------ |  BAP MCP     | ---------- | BAP Server   |
|  (any MCP    |   (stdio)    |   Server     | (WebSocket)| (Playwright) |
|   client)    |              |              |            |              |
+--------------+              +--------------+            +--------------+
                                                               |
                                                               v
                                                         +-----------+
                                                         |  Browser  |
                                                         +-----------+
  1. AI agent sends tool calls via MCP (stdio transport)
  2. BAP MCP server translates them to BAP protocol
  3. BAP Playwright server controls the browser via Playwright
  4. Results flow back to the agent

​
Two Modes

Standalone Mode (default)

Auto-starts a BAP Playwright server as a child process. No separate server setup needed. Just run the MCP server and it handles everything.

Connected Mode

Connects to an externally-managed BAP Playwright server via --url. Use when you want to share a single server across multiple MCP clients or manage the server lifecycle yourself.

​
Standalone Mode

npx @browseragentprotocol/mcp
The MCP server spawns a Playwright server internally. No configuration needed.

​
Connected Mode

Start a BAP server externally, then point the MCP server at it: 
npx @browseragentprotocol/mcp --url ws://localhost:9222

​
Quick Start

1

Run the MCP server

bash npx @browseragentprotocol/mcp
2

Connect from your AI agent

The server communicates over stdio. Configure your MCP client to launch the command above.
3

Use browser tools

Your agent now has access to 23 browser tools: navigate, observe, act, extract, screenshot, and more.

​
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 — your agent is notified of errors as they happen.

​
CLI Options

​
-b, --browser
string
default:"chrome"
Browser to use: chrome, chromium, firefox, webkit, edge.
​
-u, --url
string
Connect to an existing BAP server (skips auto-start). Example: ws://localhost:9222.
​
-p, --port
number
default:"9222"
Port for the auto-started server (standalone mode only).
​
--headless
flag
default:"true"
Run browser in headless mode (default).
​
--no-headless
flag
Show the browser window.
​
--allowed-domains
string
Comma-separated list of allowed domains. Supports wildcards (e.g., *.example.com).
​
--slim
flag
Expose only 5 essential tools. See Slim Mode.
​
--in-process
flag
Run the Playwright server in-process. See In-Process Mode.
​
-v, --verbose
flag
Enable verbose logging to stderr.

​
Programmatic Usage

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

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

await server.run();

​
Troubleshooting

On native Windows (not WSL), use the cmd /c wrapper in your MCP client config:
{
  "mcpServers": {
    "bap-browser": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@browseragentprotocol/mcp"]
    }
  }
}
Ensure Playwright browsers are installed: bash npx playwright install chromium
The MCP server tries your local Chrome first. If not found, it falls back to bundled Chromium with a warning. To use a specific browser, pass --browser chromium or --browser firefox.