The mcp-server-browserbase
server integrates Browserbase with MCP, enabling LLMs to control a remote cloud browser for web automation and interaction tasks. With this server, you can:
- Create and manage browser sessions: Start, use, and close browser sessions
- Navigate and interact with web pages: Navigate to URLs, click elements, fill input fields
- Extract content: Retrieve page content with optional CSS selectors
- Capture screenshots: Take screenshots of pages or specific elements
- Execute JavaScript: Run custom code within the browser context
- Maintain persistence: Use Browserbase Contexts to preserve cookies, authentication, and cached data
- Manage cookies: Add, retrieve, and delete cookies directly
- Configure sessions: Customize viewport dimensions, enable proxies or stealth mode (scale plan required), and inject cookies
Provides ability to target specific web page elements using CSS selectors for screenshots, content extraction, clicking, and form filling operations.
Enables execution of JavaScript code in the browser console through the browserbase_evaluate tool, allowing for dynamic interaction with web page elements and content.
Supports installation of necessary dependencies for the MCP server through npm, with specific instructions to run 'npm install' and 'npm run build' during setup.
Playwright Browserbase MCP Server
The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. Whether you’re building an AI-powered IDE, enhancing a chat interface, or creating custom AI workflows, MCP provides a standardized way to connect LLMs with the context they need.
How to setup in MCP json
You can either use our Server hosted on NPM or run it completely locally by cloning this repo.
To run on NPM (Recommended)
Go into your MCP Config JSON and add the Browserbase Server:
Thats it! Reload your MCP client and Claude will be able to use Browserbase.
To run 100% local:
Then in your MCP Config JSON run the server. To run locally we can use STDIO or self-host over SSE.
STDIO:
To your MCP Config JSON file add the following:
SSE:
Run the following command in your terminal. You can add any flags (see options below) that you see fit to customize your configuration.
Then in your MCP Config JSON file put the following:
Then reload your MCP client and you should be good to go!
Flags Explained:
The Browserbase MCP server accepts the following command-line flags:
Flag | Description |
---|---|
--browserbaseApiKey <key> | Your Browserbase API key for authentication |
--browserbaseProjectId <id> | Your Browserbase project ID |
--proxies | Enable Browserbase proxies for the session |
--advancedStealth | Enable Browserbase Advanced Stealth (Only for Scale Plan Users) |
--contextId <contextId> | Specify a Browserbase Context ID to use |
--persist [boolean] | Whether to persist the Browserbase context (default: true) |
--port <port> | Port to listen on for HTTP/SSE transport |
--host <host> | Host to bind server to (default: localhost, use 0.0.0.0 for all interfaces) |
--cookies [json] | JSON array of cookies to inject into the browser |
--browserWidth <width> | Browser viewport width (default: 1024) |
--browserHeight <height> | Browser viewport height (default: 768) |
These flags can be passed directly to the CLI or configured in your MCP configuration file.
NOTE:
Currently, these flags can only be used with the local server (npx @browserbasehq/mcp).
Flags & Example Configs
Proxies
Here are our docs on Proxies.
To use proxies in STDIO, set the --proxies flag in your MCP Config:
Advanced Stealth
Here are our docs on Advanced Stealth.
To use proxies in STDIO, set the --advancedStealth flag in your MCP Config:
Contexts
Here are our docs on Contexts
To use contexts in STDIO, set the --contextId flag in your MCP Config:
Cookie Injection
Why would you need to inject cookies? Our context API currently works on persistent cookies, but not session cookies. So sometimes our persistent auth might not work (we're working hard to add this functionality).
You can flag cookies into the MCP by adding the cookies.json to your MCP Config.
To use proxies in STDIO, set the --proxies flag in your MCP Config. Your cookies JSON must be in the type of Playwright Cookies
Browser Viewport Sizing
The default viewport sizing for a browser session is 1024 x 768. You can adjust the Browser viewport sizing with browserWidth and browserHeight flags.
Here's how to use it for custom browser sizing. We recommend to stick with 16:9 aspect ratios (ie: 1920 x 1080, 1280, 720, 1024 x 768)
Structure
src/
: TypeScript source codeindex.ts
: Main entry point, env checks, shutdownserver.ts
: MCP Server setup and request routingsessionManager.ts
: Handles Browserbase session creation/managementtools/
: Tool definitions and implementationsresources/
: Resource (screenshot) handlingtypes.ts
: Shared TypeScript types
dist/
: Compiled JavaScript outputtests/
: Placeholder for testsutils/
: Placeholder for utility scriptsDockerfile
: For building a Docker image- Configuration files (
.json
,.ts
,.mjs
,.npmignore
)
Contexts for Persistence
This server supports Browserbase's Contexts feature, which allows persisting cookies, authentication, and cached data across browser sessions:
- Creating a Context:
- Using a Context with a Session:
- Deleting a Context:
Contexts make it much easier to:
- Maintain login state across sessions
- Reduce page load times by preserving cache
- Avoid CAPTCHAs and detection by reusing browser fingerprints
Cookie Management
This server also provides direct cookie management capabilities:
- Adding Cookies:
- Getting Cookies:
- Deleting Cookies:
These tools are useful for:
- Setting authentication cookies without navigating to login pages
- Backing up and restoring cookie state
- Debugging cookie-related issues
- Manipulating cookie attributes (expiration, security flags, etc.)
TODO/Roadmap
- Implement true
ref
-based interaction logic for click, type, drag, hover, select_option. - Implement element-specific screenshots using
ref
. - Add more standard MCP tools (tabs, navigation, etc.).
- Add tests.
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
This server provides cloud browser automation capabilities using Browserbase, Puppeteer, and Stagehand. This server enables LLMs to interact with web pages, take screenshots, and execute JavaScript in a cloud browser environment.
Related MCP Servers
- AsecurityFlicenseAqualityA server that enables browser automation using Playwright, allowing interaction with web pages, capturing screenshots, and executing JavaScript in a browser environment through LLMs.Last updated -129,4571TypeScript
- AsecurityFlicenseAqualityEnables LLMs to perform web browsing tasks, take screenshots, and execute JavaScript using Puppeteer for browser automation.Last updated -415,5021JavaScript
- AsecurityFlicenseAqualityEnables browser automation for LLMs on Linux display servers, supporting web interaction, screenshots, and JavaScript execution in a real browser.Last updated -754JavaScript
- -securityAlicense-qualityA Model Context Protocol server that enables LLMs to automate web browsers using Puppeteer, allowing navigation, screenshots, form filling, and JavaScript execution in a real browser environment.Last updated -JavaScriptMIT License