base on Allow LLMs to control a browser with Browserbase and Stagehand # Browserbase MCP Server [](https://smithery.ai/server/@browserbasehq/mcp-browserbase)  [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. This 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. ## What's New in Stagehand v3 Powered by [Stagehand v3.0](https://github.com/browserbase/stagehand), this MCP server now includes: - **20-40% Faster Performance**: Speed improvements across all core operations (`act`, `extract`, `observe`) through automatic caching - **Enhanced Extraction**: Targeted extraction and observation across iframes and shadow roots - **Improved Schemas**: Streamlined extract schemas for more intuitive data extraction - **Advanced Selector Support**: CSS selector support with improved element targeting - **Multi-Browser Support**: Compatible with Playwright, Puppeteer, and Patchright - **New Primitives**: Built-in `page`, `locator`, `frameLocator`, and `deepLocator` for simplified automation - **Experimental Features**: Enable cutting-edge capabilities with the `--experimental` flag For more details, visit the [Stagehand v3 documentation](https://docs.stagehand.dev/). ## Features | Feature | Description | | ------------------ | ----------------------------------------------------------- | | Browser Automation | Control and orchestrate cloud browsers via Browserbase | | Data Extraction | Extract structured data from any webpage | | Web Interaction | Navigate, click, and fill forms with ease | | Screenshots | Capture full-page and element screenshots | | Model Flexibility | Supports multiple models (OpenAI, Claude, Gemini, and more) | | Vision Support | Use annotated screenshots for complex DOMs | | Session Management | Create, manage, and close browser sessions | | High Performance | 20-40% faster operations with automatic caching (v3) | | Advanced Selectors | Enhanced CSS selector support for precise element targeting | ## How to Setup ### Quickstarts: #### Add to Cursor Copy and Paste this link in your Browser: ```text cursor://anysphere.cursor-deeplink/mcp/install?name=browserbase&config=eyJjb21tYW5kIjoibnB4IEBicm93c2VyYmFzZWhxL21jcCIsImVudiI6eyJCUk9XU0VSQkFTRV9BUElfS0VZIjoiIiwiQlJPV1NFUkJBU0VfUFJPSkVDVF9JRCI6IiIsIkdFTUlOSV9BUElfS0VZIjoiIn19 ``` We 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. ## SHTTP: To use the Browserbase MCP Server through our remote hosted URL, add the following to your configuration. Go to [smithery.ai](https://smithery.ai/server/@browserbasehq/mcp-browserbase) and enter your API keys and configuration to get a remote hosted URL. When 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).  If your client supports SHTTP: ```json { "mcpServers": { "browserbase": { "type": "http", "url": "your-smithery-url.com" } } } ``` If your client doesn't support SHTTP: ```json { "mcpServers": { "browserbase": { "command": "npx", "args": ["mcp-remote", "your-smithery-url.com"] } } } ``` ## STDIO: You can either use our Server hosted on NPM or run it completely locally by cloning this repo. > **❗️ 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. ### To run on NPM (Recommended) Go into your MCP Config JSON and add the Browserbase Server: ```json { "mcpServers": { "browserbase": { "command": "npx", "args": ["@browserbasehq/mcp-server-browserbase"], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` That's it! Reload your MCP client and Claude will be able to use Browserbase. ### To run 100% local: #### Option 1: Direct installation ```bash # Clone the Repo git clone https://github.com/browserbase/mcp-server-browserbase.git cd mcp-server-browserbase # Install the dependencies and build the project npm install && npm run build ``` #### Option 2: Docker ```bash # Clone the Repo git clone https://github.com/browserbase/mcp-server-browserbase.git cd mcp-server-browserbase # Build the Docker image docker build -t mcp-browserbase . ``` Then in your MCP Config JSON run the server. To run locally we can use STDIO or self-host SHTTP. ### STDIO: #### Using Direct Installation To your MCP Config JSON file add the following: ```json { "mcpServers": { "browserbase": { "command": "node", "args": ["/path/to/mcp-server-browserbase/cli.js"], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` #### Using Docker To your MCP Config JSON file add the following: ```json { "mcpServers": { "browserbase": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "BROWSERBASE_API_KEY", "-e", "BROWSERBASE_PROJECT_ID", "-e", "GEMINI_API_KEY", "mcp-browserbase" ], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` Then reload your MCP client and you should be good to go! ## Configuration The Browserbase MCP server accepts the following command-line flags: | Flag | Description | | -------------------------- | --------------------------------------------------------------------------- | | `--proxies` | Enable Browserbase proxies for the session | | `--advancedStealth` | Enable Browserbase Advanced Stealth (Only for Scale Plan Users) | | `--keepAlive` | Enable Browserbase Keep Alive Session | | `--contextId <contextId>` | Specify a Browserbase Context ID to use | | `--persist` | Whether to persist the Browserbase context (default: true) | | `--port <port>` | Port to listen on for HTTP/SHTTP transport | | `--host <host>` | Host to bind server to (default: localhost, use 0.0.0.0 for all interfaces) | | `--browserWidth <width>` | Browser viewport width (default: 1024) | | `--browserHeight <height>` | Browser viewport height (default: 768) | | `--modelName <model>` | The model to use for Stagehand (default: gemini-2.0-flash) | | `--modelApiKey <key>` | API key for the custom model provider (required when using custom models) | | `--experimental` | Enable experimental features (default: false) | 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-server-browserbase or Docker). ### Using Configuration Flags with Docker When using Docker, you can pass configuration flags as additional arguments after the image name. Here's an example with the `--proxies` flag: ```json { "mcpServers": { "browserbase": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "BROWSERBASE_API_KEY", "-e", "BROWSERBASE_PROJECT_ID", "-e", "GEMINI_API_KEY", "mcp-browserbase", "--proxies" ], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` You can also run the Docker container directly from the command line: ```bash docker run --rm -i \ -e BROWSERBASE_API_KEY=your_api_key \ -e BROWSERBASE_PROJECT_ID=your_project_id \ -e GEMINI_API_KEY=your_gemini_key \ mcp-browserbase --proxies ``` ## Configuration Examples ### Proxies Here are our docs on [Proxies](https://docs.browserbase.com/features/proxies). To use proxies, set the --proxies flag in your MCP Config: ```json { "mcpServers": { "browserbase": { "command": "npx", "args": ["@browserbasehq/mcp-server-browserbase", "--proxies"], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` ### Advanced Stealth Here are our docs on [Advanced Stealth](https://docs.browserbase.com/features/stealth-mode#advanced-stealth-mode). To use advanced stealth, set the --advancedStealth flag in your MCP Config: ```json { "mcpServers": { "browserbase": { "command": "npx", "args": ["@browserbasehq/mcp-server-browserbase", "--advancedStealth"], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` ### Contexts Here are our docs on [Contexts](https://docs.browserbase.com/features/contexts) To use contexts, set the --contextId flag in your MCP Config: ```json { "mcpServers": { "browserbase": { "command": "npx", "args": [ "@browserbasehq/mcp-server-browserbase", "--contextId", "<YOUR_CONTEXT_ID>" ], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` ### 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 x 720, 1024 x 768) ```json { "mcpServers": { "browserbase": { "command": "npx", "args": [ "@browserbasehq/mcp-server-browserbase", "--browserHeight 1080", "--browserWidth 1920" ], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` ### Experimental Features Stagehand 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. To enable experimental features: ```json { "mcpServers": { "browserbase": { "command": "npx", "args": ["@browserbasehq/mcp-server-browserbase", "--experimental"], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "", "GEMINI_API_KEY": "" } } } } ``` _Note: Experimental features may change or be removed in future releases. Use them at your own discretion._ ### Model Configuration Stagehand 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. **Important**: When using any custom model (non-default), you must provide your own API key for that model provider using the `--modelApiKey` flag. Here's how to configure different models: ```json { "mcpServers": { "browserbase": { "command": "npx", "args": [ "@browserbasehq/mcp-server-browserbase", "--modelName", "anthropic/claude-sonnet-4.5", "--modelApiKey", "your-anthropic-api-key" ], "env": { "BROWSERBASE_API_KEY": "", "BROWSERBASE_PROJECT_ID": "" } } } } ``` _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._ ### Resources The server provides access to screenshot resources: 1. **Screenshots** (`screenshot://<screenshot-name>`) - PNG images of captured screenshots ## Key Features - **AI-Powered Automation**: Natural language commands for web interactions - **Multi-Model Support**: Works with OpenAI, Claude, Gemini, and more - **Screenshot Capture**: Full-page and element-specific screenshots - **Data Extraction**: Intelligent content extraction from web pages - **Proxy Support**: Enterprise-grade proxy capabilities - **Stealth Mode**: Advanced anti-detection features - **Context Persistence**: Maintain authentication and state across sessions For more information about the Model Context Protocol, visit: - [MCP Documentation](https://modelcontextprotocol.io/docs) - [MCP Specification](https://spec.modelcontextprotocol.io/) For the official MCP Docs: - [Browserbase MCP](https://docs.browserbase.com/integrations/mcp/introduction) ## License Licensed under the Apache 2.0 License. Copyright 2025 Browserbase, Inc. ", Assign "at most 3 tags" to the expected json: {"id":"13103","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"