parallel-browser-mcp
Allows browser automation using Cloudflare Browser Run, enabling tools to navigate, click, fill forms, take screenshots, and perform other browser actions in a headless browser managed by Cloudflare.
parallel-browser-mcp
parallel-browser-mcp is an MCP server for parallel browser automation. It exposes a numeric session model over MCP so one client can create and control multiple browser sessions at the same time across multiple browser providers.
Supported providers:
playwrightfor local Chromiumbrowserbasevia@browserbasehq/sdkanchorviaanchorbrowsercloudflarevia Cloudflare Browser Run
Each browser session gets a numeric ID like 1, 2, 3, and every browser_* tool accepts a sessionId.
Features
Multiple concurrent browser sessions in memory
Provider abstraction shared across Browserbase, Anchor Browser, Cloudflare Browser Run, and local Playwright
MCP session tools:
start_sessionclose_sessionclose_all_sessionsget_sessions
Browser tools:
browser_navigatebrowser_go_backbrowser_clickbrowser_fillbrowser_fill_formbrowser_screenshotbrowser_snapshotbrowser_hoverbrowser_dragbrowser_select_optionbrowser_generate_locatorbrowser_get_page_structurebrowser_evaluatebrowser_keyboard_pressbrowser_keyboard_typebrowser_mouse_movebrowser_mouse_click_xybrowser_mouse_dragbrowser_upload_filebrowser_wait_for_selectorbrowser_wait_for_timeout
Related MCP server: open_browser_use
Quick Start
corepack pnpm install
corepack pnpm buildRun locally over stdio:
node dist/index.jsRun it as an npm package CLI:
npx parallel-browser-mcp@latestConfiguration
Provider-specific settings are configured at the MCP server configuration level, not per tool call.
The server reads config in this order:
BROWSER_MCP_CONFIGBROWSER_MCP_CONFIG_PATHdirect env defaults
built-in defaults
Recommended config shape:
{
"defaultProvider": "playwright",
"providers": {
"browserbase": {
"projectId": "proj_123",
"keepAlive": true
},
"anchor": {
"recording": false
},
"playwright": {
"launchOptions": {
"headless": true
},
"useCloakBrowser": false
}
}
}Stealth Chromium via CloakBrowser
The playwright provider can optionally launch CloakBrowser instead of vanilla Chromium for sessions that need to bypass bot detection. Enable it per-config or via env:
{
"providers": {
"playwright": { "useCloakBrowser": true }
}
}PLAYWRIGHT_USE_CLOAKBROWSER=truecloakbrowser is an optional peer — install it only when you need stealth:
npm install cloakbrowserThe CloakBrowser binary (~200MB stealth Chromium) is downloaded automatically on the first session launch. Existing launchOptions / contextOptions continue to apply, and the rest of the provider behaves identically to standard Playwright.
Required credentials by provider:
playwright: nonebrowserbase:BROWSERBASE_API_KEY, plus aprojectIdin config orBROWSERBASE_PROJECT_IDanchor:ANCHOR_API_KEYcloudflare:CLOUDFLARE_API_TOKEN,CLOUDFLARE_ACCOUNT_ID
Optional env defaults:
BROWSERBASE_PROJECT_IDBROWSERBASE_KEEP_ALIVEBROWSERBASE_CONTEXT_IDBROWSERBASE_PERSISTPLAYWRIGHT_STORAGE_STATE_PATHPLAYWRIGHT_EXECUTABLE_PATHPLAYWRIGHT_CHANNELPLAYWRIGHT_USE_CLOAKBROWSER(trueto launch stealth Chromium via CloakBrowser; requiresnpm install cloakbrowser)
Installation
Use the standard config below in any MCP client that supports stdio:
{
"mcpServers": {
"parallel-browser-mcp": {
"command": "npx",
"args": ["parallel-browser-mcp@latest"],
"env": {
"BROWSER_MCP_CONFIG": "{\"defaultProvider\":\"playwright\",\"providers\":{\"playwright\":{\"launchOptions\":{\"headless\":true}}}}",
"BROWSERBASE_API_KEY": "your_browserbase_key",
"ANCHOR_API_KEY": "your_anchor_key"
}
}
}
}Use the Claude Code CLI to add the server:
claude mcp add parallel-browser-mcp npx parallel-browser-mcp@latestIf you need provider configuration, add the environment variables in your Claude MCP config using the standard config above.
Follow the Claude Desktop MCP install flow and use the standard config above in the local MCP configuration file.
Use the Codex CLI:
codex mcp add parallel-browser-mcp npx "parallel-browser-mcp@latest"Or add this to ~/.codex/config.toml:
[mcp_servers.parallel-browser-mcp]
command = "npx"
args = ["parallel-browser-mcp@latest"]Use the Copilot CLI interactive flow:
/mcp addOr add this to ~/.copilot/mcp-config.json:
{
"mcpServers": {
"parallel-browser-mcp": {
"type": "local",
"command": "npx",
"tools": ["*"],
"args": ["parallel-browser-mcp@latest"],
"env": {
"BROWSER_MCP_CONFIG": "{\"defaultProvider\":\"playwright\",\"providers\":{\"playwright\":{\"launchOptions\":{\"headless\":true}}}}",
"BROWSERBASE_API_KEY": "your_browserbase_key",
"ANCHOR_API_KEY": "your_anchor_key"
}
}
}
}Go to Cursor Settings -> MCP -> Add new MCP Server, then use:
command:
npxargs:
parallel-browser-mcp@latest
Or paste the standard config above into the MCP config editor.
Add the server to .gemini/settings.json:
{
"mcpServers": {
"parallel-browser-mcp": {
"command": "npx",
"args": ["parallel-browser-mcp@latest"],
"env": {
"BROWSER_MCP_CONFIG": "{\"defaultProvider\":\"playwright\",\"providers\":{\"playwright\":{\"launchOptions\":{\"headless\":true}}}}",
"BROWSERBASE_API_KEY": "your_browserbase_key",
"ANCHOR_API_KEY": "your_anchor_key"
}
}
}
}Use the MCP install flow in VS Code with the standard config above, or install with the VS Code CLI:
code --add-mcp '{"name":"parallel-browser-mcp","command":"npx","args":["parallel-browser-mcp@latest"]}'Example Flow
Call
start_sessionwith{ "provider": "playwright" }Read the returned session
idCall
browser_navigatewith{ "sessionId": 1, "url": "https://example.com" }Call any additional
browser_*tool with the samesessionIdCall
close_sessionwhen done
Development
corepack pnpm install
corepack pnpm typecheck
corepack pnpm test
corepack pnpm test:coverage
corepack pnpm build
corepack pnpm smoke:localPublishing
This repo is set up to publish as an npm package:
the CLI entrypoint is
parallel-browser-mcpproduction builds exclude tests and smoke scripts
the published package only includes
dist,README.md, and.env.example
Before publishing:
corepack pnpm typecheck
corepack pnpm test
corepack pnpm build
npm pack --dry-runGitHub Actions publishing:
.github/workflows/publish.ymlpublishes to npm on GitHub release publication or manual dispatchset the
NPM_TOKENrepository secret before using the publish workflow
Examples
examples/localcontains a standalone npm package that connects toparallel-browser-mcpwith@langchain/mcp-adaptersand runs a LangChain agent against the local Playwright provider.examples/browserbasecontains a standalone npm package that connects LangChain to the published MCP server with Browserbase config and prompts the agent to usebrowser_screenshot.examples/anchorcontains a standalone npm package that connects LangChain to the published MCP server with Anchor config and prompts the agent to usebrowser_snapshot.examples/cloudflarecontains a standalone npm package that connects LangChain to the published MCP server with Cloudflare Browser Run config and prompts the agent to usebrowser_snapshot.The root
.npmignoreexcludes the fullexamplesdirectory from npm publishing.
Testing
The repo includes:
unit coverage for config loading, providers, registry behavior, session tools, and representative browser tools
a local Playwright smoke script in
src/smoke/localSmoke.ts
Notes
start_sessionis intentionally small. Provider-specific behavior belongs in MCP configuration, not tool inputs.The server logs to stderr so stdout stays clean for MCP JSON-RPC traffic.
Browserbase and Anchor Browser are normalized to Playwright page operations after connection, so the browser tools stay provider-agnostic.
Available Tools
26 toolsbrowser_clickBrowser ClickC
Click an element by selector.
Inputs: selector (required), sessionId (required), timeout.
browser_dom_queryBrowser DOM QueryC
Query element presence, count, and state without waiting.
Inputs: selector (required), sessionId (required).
browser_dragBrowser DragC
Drag from one element to another.
Inputs: sessionId (required), sourceSelector (required), targetSelector (required), timeout.
browser_evaluateBrowser EvaluateC
Run JavaScript in the page context.
Inputs: script (required), sessionId (required), selector.
browser_fillBrowser FillC
Fill a field with text.
Inputs: value (required), selector (required), sessionId (required), timeout.
browser_fill_formBrowser Fill FormC
Fill multiple form fields.
Inputs: fields (required), sessionId (required).
browser_generate_locatorBrowser Generate LocatorC
Generate locator suggestions for an element.
Inputs: selector (required), sessionId (required).
browser_get_page_structureBrowser Get Page StructureC
Return a readable page structure summary.
Inputs: sessionId (required), maxDepth, selector, maxChildren.
browser_go_backBrowser Go BackC
Go back in browser history.
Inputs: sessionId (required).
browser_hoverBrowser HoverC
Hover over an element by selector.
Inputs: selector (required), sessionId (required), timeout.
browser_keyboard_pressBrowser Keyboard PressC
Press a keyboard key or key chord.
Inputs: key (required), sessionId (required).
browser_keyboard_typeBrowser Keyboard TypeC
Type text into the active page.
Inputs: text (required), sessionId (required), delay.
browser_mouse_click_xyBrowser Mouse Click XYC
Click at viewport coordinates.
Inputs: x (required), y (required), sessionId (required).
browser_mouse_dragBrowser Mouse DragD
Drag the mouse from one point to another.
Inputs: endX (required), endY (required), startX (required), startY (required), +1 more.
browser_mouse_moveBrowser Mouse MoveC
Move the mouse to viewport coordinates.
Inputs: x (required), y (required), sessionId (required).
browser_screenshotBrowser ScreenshotC
Capture a screenshot of the current page.
Inputs: sessionId (required), fullPage.
browser_select_optionBrowser Select OptionC
Select options in a select element.
Inputs: values (required), selector (required), sessionId (required), timeout.
browser_snapshotBrowser SnapshotC
Return a structured page snapshot.
Inputs: sessionId (required), maxDepth, selector, maxChildren.
browser_upload_fileBrowser Upload FileC
Upload files to a file input.
Inputs: selector (required), filePaths (required), sessionId (required).
browser_wait_for_selectorBrowser Wait For SelectorC
Wait for a selector to reach a state.
Inputs: selector (required), sessionId (required), state, timeout.
browser_wait_for_timeoutBrowser Wait For TimeoutC
Wait a fixed number of milliseconds.
Inputs: sessionId (required), milliseconds (required).
close_all_sessionsClose All SessionsA
Close all active browser sessions.
Inputs: no named parameters.
close_sessionClose SessionB
Close a browser session by numeric session ID.
Inputs: sessionId (required).
get_sessionsGet SessionsA
List all active browser sessions.
Inputs: no named parameters.
start_sessionStart SessionC
Start a browser session using the configured provider.
Inputs: provider, sessionName.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Most browser actions are individually clear, but several near-overlapping pairs exist: browser_snapshot, browser_get_page_structure, and browser_dom_query all describe page/DOM inspection, while browser_fill, browser_keyboard_type, browser_click, and browser_mouse_click_xy cover similar input territory. Descriptions reduce some ambiguity, but an agent could still easily select the wrong tool.
Session tools follow a clean verb_noun pattern like start_session and close_session, while browser actions consistently use a browser_ prefix followed by descriptive verbs. The mixed prefixes are minor and the naming remains predictable and readable.
With 26 tools, this server sits above the 25+ threshold and feels too heavy for a single MCP surface. Several mouse, keyboard, and DOM primitives could be consolidated or split into a separate server without losing functionality.
The toolset covers the core browser automation lifecycle well: navigation, DOM interaction, form filling, mouse/keyboard input, screenshots, uploads, waits, and session management. Notable gaps like tab/window management, cookies, and frame handling are missing, but agents can often work around them via browser_evaluate or separate sessions.
Maintenance
Related MCP Connectors
Unofficial Browserless MCP — wraps the Browserless headless-Chromium REST API (browserless.io)
Official Browserless MCP server: browser automation, scraping, screenshots and PDFs for AI agents.
MCP server to assist with JxBrowser development.
Browser MCP: local Chrome 0.7.22, Linux VPS and limited Cloud, with human handoff and OAuth.
Related MCP Servers
- AlicenseBqualityDmaintenanceA concurrent browser MCP server that supports multiple parallel browser instances2021 npm12Apache 2.0
- AlicenseNot gradedqualityBmaintenanceMCP server for browser automation, exposing tools for tab management, navigation, CDP, action plans, and cleanup.428MIT
- AlicenseBqualityDmaintenanceA production-ready MCP server that exposes Selenium 4 browser automation as MCP tools.27MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for browser automation with shared authentication and built-in UI auditing.MIT