Browserbase MCP Server

1# Browserbase MCP Server
2 
3[![smithery badge](https://smithery.ai/badge/@browserbasehq/mcp-browserbase)](https://smithery.ai/server/@browserbasehq/mcp-browserbase)
4 
5![cover](assets/cover.png)
6 
7[The Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 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.
8 
9This server provides cloud browser automation capabilities using [Browserbase](https://www.browserbase.com/) and [Stagehand](https://github.com/browserbase/stagehand). It enables LLMs to interact with web pages, take screenshots, extract information, and perform automated actions with atomic precision.
10 
11## What's New in Stagehand v3
12 
13Powered by [Stagehand v3.0](https://github.com/browserbase/stagehand), this MCP server now includes:
14 
15- **20-40% Faster Performance**: Speed improvements across all core operations (`act`, `extract`, `observe`) through automatic caching
16- **Enhanced Extraction**: Targeted extraction and observation across iframes and shadow roots
17- **Improved Schemas**: Streamlined extract schemas for more intuitive data extraction
18- **Advanced Selector Support**: CSS selector support with improved element targeting
19- **Multi-Browser Support**: Compatible with Playwright, Puppeteer, and Patchright
20- **New Primitives**: Built-in `page`, `locator`, `frameLocator`, and `deepLocator` for simplified automation
21- **Experimental Features**: Enable cutting-edge capabilities with the `--experimental` flag
22 
23For more details, visit the [Stagehand v3 documentation](https://docs.stagehand.dev/).
24 
25## Features
26 
27| Feature            | Description                                                 |
28| ------------------ | ----------------------------------------------------------- |
29| Browser Automation | Control and orchestrate cloud browsers via Browserbase      |
30| Data Extraction    | Extract structured data from any webpage                    |
31| Web Interaction    | Navigate, click, and fill forms with ease                   |
32| Screenshots        | Capture full-page and element screenshots                   |
33| Model Flexibility  | Supports multiple models (OpenAI, Claude, Gemini, and more) |
34| Vision Support     | Use annotated screenshots for complex DOMs                  |
35| Session Management | Create, manage, and close browser sessions                  |
36| High Performance   | 20-40% faster operations with automatic caching (v3)        |
37| Advanced Selectors | Enhanced CSS selector support for precise element targeting |
38 
39## How to Setup
40 
41### Quickstarts:
42 
43#### Add to Cursor
44 
45Copy and Paste this link in your Browser:
46 
47```text
48cursor://anysphere.cursor-deeplink/mcp/install?name=browserbase&config=eyJjb21tYW5kIjoibnB4IEBicm93c2VyYmFzZWhxL21jcCIsImVudiI6eyJCUk9XU0VSQkFTRV9BUElfS0VZIjoiIiwiQlJPV1NFUkJBU0VfUFJPSkVDVF9JRCI6IiIsIkdFTUlOSV9BUElfS0VZIjoiIn19
49```
50 
51We currently support 2 transports for our MCP server, STDIO and SHTTP. We recommend you use SHTTP with our remote hosted url to take advantage of the server at full capacity.
52 
53## SHTTP:
54 
55To use the Browserbase MCP Server through our remote hosted URL, add the following to your configuration.
56 
57Go to [smithery.ai](https://smithery.ai/server/@browserbasehq/mcp-browserbase) and enter your API keys and configuration to get a remote hosted URL.
58When using our remote hosted server, we provide the LLM costs for Gemini, the [best performing model](https://www.stagehand.dev/evals) in [Stagehand](https://www.stagehand.dev).
59 
60![Smithery Image](assets/smithery.jpg)
61 
62If your client supports SHTTP:
63 
64```json
65{
66  "mcpServers": {
67    "browserbase": {
68      "type": "http",
69      "url": "your-smithery-url.com"
70    }
71  }
72}
73```
74 
75If your client doesn't support SHTTP:
76 
77```json
78{
79  "mcpServers": {
80    "browserbase": {
81      "command": "npx",
82      "args": ["mcp-remote", "your-smithery-url.com"]
83    }
84  }
85}
86```
87 
88## STDIO:
89 
90You can either use our Server hosted on NPM or run it completely locally by cloning this repo.
91 
92> **❗️ Important:** If you want to use a different model you have to add --modelName to the args and provide that respective key as an arg. More info below.
93 
94### To run on NPM (Recommended)
95 
96Go into your MCP Config JSON and add the Browserbase Server:
97 
98```json
99{
100  "mcpServers": {
101    "browserbase": {
102      "command": "npx",
103      "args": ["@browserbasehq/mcp-server-browserbase"],
104      "env": {
105        "BROWSERBASE_API_KEY": "",
106        "BROWSERBASE_PROJECT_ID": "",
107        "GEMINI_API_KEY": ""
108      }
109    }
110  }
111}
112```
113 
114That's it! Reload your MCP client and Claude will be able to use Browserbase.
115 
116### To run 100% local:
117 
118#### Option 1: Direct installation
119 
120```bash
121# Clone the Repo
122git clone https://github.com/browserbase/mcp-server-browserbase.git
123cd mcp-server-browserbase
124 
125# Install the dependencies and build the project
126npm install && npm run build
127```
128 
129#### Option 2: Docker
130 
131```bash
132# Clone the Repo
133git clone https://github.com/browserbase/mcp-server-browserbase.git
134cd mcp-server-browserbase
135 
136# Build the Docker image
137docker build -t mcp-browserbase .
138```
139 
140Then in your MCP Config JSON run the server. To run locally we can use STDIO or self-host SHTTP.
141 
142### STDIO:
143 
144#### Using Direct Installation
145 
146To your MCP Config JSON file add the following:
147 
148```json
149{
150  "mcpServers": {
151    "browserbase": {
152      "command": "node",
153      "args": ["/path/to/mcp-server-browserbase/cli.js"],
154      "env": {
155        "BROWSERBASE_API_KEY": "",
156        "BROWSERBASE_PROJECT_ID": "",
157        "GEMINI_API_KEY": ""
158      }
159    }
160  }
161}
162```
163 
164#### Using Docker
165 
166To your MCP Config JSON file add the following:
167 
168```json
169{
170  "mcpServers": {
171    "browserbase": {
172      "command": "docker",
173      "args": [
174        "run",
175        "--rm",
176        "-i",
177        "-e",
178        "BROWSERBASE_API_KEY",
179        "-e",
180        "BROWSERBASE_PROJECT_ID",
181        "-e",
182        "GEMINI_API_KEY",
183        "mcp-browserbase"
184      ],
185      "env": {
186        "BROWSERBASE_API_KEY": "",
187        "BROWSERBASE_PROJECT_ID": "",
188        "GEMINI_API_KEY": ""
189      }
190    }
191  }
192}
193```
194 
195Then reload your MCP client and you should be good to go!
196 
197## Configuration
198 
199The Browserbase MCP server accepts the following command-line flags:
200 
201| Flag                       | Description                                                                 |
202| -------------------------- | --------------------------------------------------------------------------- |
203| `--proxies`                | Enable Browserbase proxies for the session                                  |
204| `--advancedStealth`        | Enable Browserbase Advanced Stealth (Only for Scale Plan Users)             |
205| `--keepAlive`              | Enable Browserbase Keep Alive Session                                       |
206| `--contextId <contextId>`  | Specify a Browserbase Context ID to use                                     |
207| `--persist`                | Whether to persist the Browserbase context (default: true)                  |
208| `--port <port>`            | Port to listen on for HTTP/SHTTP transport                                  |
209| `--host <host>`            | Host to bind server to (default: localhost, use 0.0.0.0 for all interfaces) |
210| `--browserWidth <width>`   | Browser viewport width (default: 1024)                                      |
211| `--browserHeight <height>` | Browser viewport height (default: 768)                                      |
212| `--modelName <model>`      | The model to use for Stagehand (default: gemini-2.0-flash)                  |
213| `--modelApiKey <key>`      | API key for the custom model provider (required when using custom models)   |
214| `--experimental`           | Enable experimental features (default: false)                               |
215 
216These flags can be passed directly to the CLI or configured in your MCP configuration file.
217 
218### NOTE:
219 
220Currently, these flags can only be used with the local server (npx @browserbasehq/mcp-server-browserbase or Docker).
221 
222### Using Configuration Flags with Docker
223 
224When using Docker, you can pass configuration flags as additional arguments after the image name. Here's an example with the `--proxies` flag:
225 
226```json
227{
228  "mcpServers": {
229    "browserbase": {
230      "command": "docker",
231      "args": [
232        "run",
233        "--rm",
234        "-i",
235        "-e",
236        "BROWSERBASE_API_KEY",
237        "-e",
238        "BROWSERBASE_PROJECT_ID",
239        "-e",
240        "GEMINI_API_KEY",
241        "mcp-browserbase",
242        "--proxies"
243      ],
244      "env": {
245        "BROWSERBASE_API_KEY": "",
246        "BROWSERBASE_PROJECT_ID": "",
247        "GEMINI_API_KEY": ""
248      }
249    }
250  }
251}
252```
253 
254You can also run the Docker container directly from the command line:
255 
256```bash
257docker run --rm -i \
258  -e BROWSERBASE_API_KEY=your_api_key \
259  -e BROWSERBASE_PROJECT_ID=your_project_id \
260  -e GEMINI_API_KEY=your_gemini_key \
261  mcp-browserbase --proxies
262```
263 
264## Configuration Examples
265 
266### Proxies
267 
268Here are our docs on [Proxies](https://docs.browserbase.com/features/proxies).
269 
270To use proxies, set the --proxies flag in your MCP Config:
271 
272```json
273{
274  "mcpServers": {
275    "browserbase": {
276      "command": "npx",
277      "args": ["@browserbasehq/mcp-server-browserbase", "--proxies"],
278      "env": {
279        "BROWSERBASE_API_KEY": "",
280        "BROWSERBASE_PROJECT_ID": "",
281        "GEMINI_API_KEY": ""
282      }
283    }
284  }
285}
286```
287 
288### Advanced Stealth
289 
290Here are our docs on [Advanced Stealth](https://docs.browserbase.com/features/stealth-mode#advanced-stealth-mode).
291 
292To use advanced stealth, set the --advancedStealth flag in your MCP Config:
293 
294```json
295{
296  "mcpServers": {
297    "browserbase": {
298      "command": "npx",
299      "args": ["@browserbasehq/mcp-server-browserbase", "--advancedStealth"],
300      "env": {
301        "BROWSERBASE_API_KEY": "",
302        "BROWSERBASE_PROJECT_ID": "",
303        "GEMINI_API_KEY": ""
304      }
305    }
306  }
307}
308```
309 
310### Contexts
311 
312Here are our docs on [Contexts](https://docs.browserbase.com/features/contexts)
313 
314To use contexts, set the --contextId flag in your MCP Config:
315 
316```json
317{
318  "mcpServers": {
319    "browserbase": {
320      "command": "npx",
321      "args": [
322        "@browserbasehq/mcp-server-browserbase",
323        "--contextId",
324        "<YOUR_CONTEXT_ID>"
325      ],
326      "env": {
327        "BROWSERBASE_API_KEY": "",
328        "BROWSERBASE_PROJECT_ID": "",
329        "GEMINI_API_KEY": ""
330      }
331    }
332  }
333}
334```
335 
336### Browser Viewport Sizing
337 
338The default viewport sizing for a browser session is 1024 x 768. You can adjust the Browser viewport sizing with browserWidth and browserHeight flags.
339 
340Here's how to use it for custom browser sizing. We recommend to stick with 16:9 aspect ratios (ie: 1920 x 1080, 1280 x 720, 1024 x 768)
341 
342```json
343{
344  "mcpServers": {
345    "browserbase": {
346      "command": "npx",
347      "args": [
348        "@browserbasehq/mcp-server-browserbase",
349        "--browserHeight 1080",
350        "--browserWidth 1920"
351      ],
352      "env": {
353        "BROWSERBASE_API_KEY": "",
354        "BROWSERBASE_PROJECT_ID": "",
355        "GEMINI_API_KEY": ""
356      }
357    }
358  }
359}
360```
361 
362### Experimental Features
363 
364Stagehand v3 includes experimental features that can be enabled with the `--experimental` flag. These features provide cutting-edge capabilities that are actively being developed and refined.
365 
366To enable experimental features:
367 
368```json
369{
370  "mcpServers": {
371    "browserbase": {
372      "command": "npx",
373      "args": ["@browserbasehq/mcp-server-browserbase", "--experimental"],
374      "env": {
375        "BROWSERBASE_API_KEY": "",
376        "BROWSERBASE_PROJECT_ID": "",
377        "GEMINI_API_KEY": ""
378      }
379    }
380  }
381}
382```
383 
384_Note: Experimental features may change or be removed in future releases. Use them at your own discretion._
385 
386### Model Configuration
387 
388Stagehand defaults to using Google's Gemini 2.0 Flash model, but you can configure it to use other models like GPT-4o, Claude, or other providers.
389 
390**Important**: When using any custom model (non-default), you must provide your own API key for that model provider using the `--modelApiKey` flag.
391 
392Here's how to configure different models:
393 
394```json
395{
396  "mcpServers": {
397    "browserbase": {
398      "command": "npx",
399      "args": [
400        "@browserbasehq/mcp-server-browserbase",
401        "--modelName",
402        "anthropic/claude-sonnet-4.5",
403        "--modelApiKey",
404        "your-anthropic-api-key"
405      ],
406      "env": {
407        "BROWSERBASE_API_KEY": "",
408        "BROWSERBASE_PROJECT_ID": ""
409      }
410    }
411  }
412}
413```
414 
415_Note: The model must be supported in Stagehand. Check out the docs [here](https://docs.stagehand.dev/examples/custom_llms#supported-llms). When using any custom model, you must provide your own API key for that provider._
416 
417### Resources
418 
419The server provides access to screenshot resources:
420 
4211. **Screenshots** (`screenshot://<screenshot-name>`)
422   - PNG images of captured screenshots
423 
424## Key Features
425 
426- **AI-Powered Automation**: Natural language commands for web interactions
427- **Multi-Model Support**: Works with OpenAI, Claude, Gemini, and more
428- **Screenshot Capture**: Full-page and element-specific screenshots
429- **Data Extraction**: Intelligent content extraction from web pages
430- **Proxy Support**: Enterprise-grade proxy capabilities
431- **Stealth Mode**: Advanced anti-detection features
432- **Context Persistence**: Maintain authentication and state across sessions
433 
434For more information about the Model Context Protocol, visit:
435 
436- [MCP Documentation](https://modelcontextprotocol.io/docs)
437- [MCP Specification](https://spec.modelcontextprotocol.io/)
438 
439For the official MCP Docs:
440 
441- [Browserbase MCP](https://docs.browserbase.com/integrations/mcp/introduction)
442 
443## License
444 
445Licensed under the Apache 2.0 License.
446 
447Copyright 2025 Browserbase, Inc.
448