Content
# Browserbase MCP Server
[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, extract information, and perform automated actions.
This is a self-hostable version of the [Browserbase hosted MCP server](https://mcp.browserbase.com/mcp) with the same tools and functionality. **We recommend using the hosted version for the easiest setup.**
## Tools
This server exposes 6 tools that match the [hosted Browserbase MCP server](https://docs.browserbase.com/integrations/mcp/introduction):
| Tool | Description | Input |
| ---------- | --------------------------------------- | -------------------------- |
| `start` | Create or reuse a Browserbase session | _(none)_ |
| `end` | Close the current Browserbase session | _(none)_ |
| `navigate` | Navigate to a URL | `{ url: string }` |
| `act` | Perform an action on the page | `{ action: string }` |
| `observe` | Observe actionable elements on the page | `{ instruction: string }` |
| `extract` | Extract data from the page | `{ instruction?: string }` |
## How to Setup
We currently support 2 transports for our MCP server, STDIO and SHTTP. We recommend you use SHTTP with our hosted MCP server to take advantage of the server at full capacity.
## SHTTP (Hosted MCP):
Use the Browserbase hosted MCP server at `https://mcp.browserbase.com/mcp`. This is the easiest way to get started -- we host the server and provide the LLM costs for Gemini, the [best performing model](https://www.stagehand.dev/evals) in [Stagehand](https://www.stagehand.dev).
For full setup instructions, see the [Browserbase MCP documentation](https://docs.browserbase.com/integrations/mcp/introduction).
If your client supports SHTTP:
```json
{
"mcpServers": {
"browserbase": {
"type": "http",
"url": "https://mcp.browserbase.com/mcp"
}
}
}
```
If your client doesn't support SHTTP:
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["mcp-remote", "https://mcp.browserbase.com/mcp"]
}
}
}
```
## STDIO (Self-Hosted):
You can either use our server hosted on NPM or run it completely locally by cloning this repo.
> **Note:** 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 via NPM (Recommended)
Go into your MCP Config JSON and add the Browserbase Server:
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": ["@browserbasehq/mcp"],
"env": {
"BROWSERBASE_API_KEY": "",
"BROWSERBASE_PROJECT_ID": "",
"GEMINI_API_KEY": ""
}
}
}
}
```
That's it! Reload your MCP client and you're ready to go.
### To run 100% local:
#### Option 1: Direct installation
```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
npm install && npm run build
```
#### Option 2: Docker
```bash
git clone https://github.com/browserbase/mcp-server-browserbase.git
cd mcp-server-browserbase
docker build -t mcp-browserbase .
```
Then in your MCP Config JSON run the server:
#### Using Direct Installation
```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
```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": ""
}
}
}
}
```
## Configuration
The Browserbase MCP server accepts the following command-line flags:
| Flag | Description |
| -------------------------- | --------------------------------------------------------------------------- |
| `--proxies` | Enable Browserbase proxies for the session |
| `--verified` | Enable Browserbase Verified Identity (Only for Scale Plan Users) |
| `--advancedStealth` | Deprecated alias for `--verified` |
| `--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: google/gemini-2.5-flash-lite) |
| `--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:** These flags can only be used with the self-hosted server (npx @browserbasehq/mcp or Docker).
### Model Configuration
Stagehand defaults to using Google's Gemini 2.5 Flash Lite 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.
```json
{
"mcpServers": {
"browserbase": {
"command": "npx",
"args": [
"@browserbasehq/mcp",
"--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)._
## Links
- [Browserbase MCP Documentation](https://docs.browserbase.com/integrations/mcp/introduction)
- [MCP Documentation](https://modelcontextprotocol.io/docs)
- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [Stagehand Documentation](https://docs.stagehand.dev/)
## License
Licensed under the Apache 2.0 License.
Copyright 2025 Browserbase, Inc.
