> ## Documentation Index
> Fetch the complete documentation index at: https://docs.browserbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Browserbase MCP server setup

> Add the Browserbase MCP Server to your MCP client

## Quick installation

<Card title="Install with Cursor" icon="arrow-pointer" href="cursor://anysphere.cursor-deeplink/mcp/install?name=browserbase&config=eyJ1cmwiOiJodHRwczovL21jcC5icm93c2VyYmFzZS5jb20vbWNwP2Jyb3dzZXJiYXNlQXBpS2V5PVlPVVJfQlJPV1NFUkJBU0VfQVBJX0tFWSJ9">
  One-click installation directly in Cursor
</Card>

You can also add Browserbase MCP to Claude Code with a single command:

```bash theme={null}
claude mcp add --transport http browserbase "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY"
```

Browserbase supports both local STDIO and hosted [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) (SHTTP). Hosted [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) is recommended for most users.

## Endpoint

Hosted [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) endpoint (served on Browserbase infrastructure):

```text theme={null}
https://mcp.browserbase.com/mcp
```

## Prerequisites

<Steps>
  <Step title="Get your Browserbase credentials">
    Get your Browserbase API key from the [Browserbase Dashboard](https://www.browserbase.com/overview).

    <Frame>
      <img src="https://mintcdn.com/browserbase/giE_cpy18f2mWHqr/images/quickstart/api_key.png?fit=max&auto=format&n=giE_cpy18f2mWHqr&q=85&s=4ac94a8f69cec20bd17b2a8788169062" alt="Browserbase API Key settings" width="3410" height="1864" data-path="images/quickstart/api_key.png" />
    </Frame>

    Then copy your API Key directly from the input.
  </Step>
</Steps>

## Query parameters (hosted [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http))

### Required for tool calls

<CardGroup cols={1}>
  <Card title="browserbaseApiKey" icon="key">
    Browserbase API key.
  </Card>
</CardGroup>

### Optional

| Query Param   | Type           | Behavior                                   |
| ------------- | -------------- | ------------------------------------------ |
| `modelName`   | string         | Defaults to `google/gemini-2.5-flash-lite` |
| `modelApiKey` | string         | Required when `modelName` is non-default   |
| `keepAlive`   | boolean string | `"true"` or `"false"`                      |
| `proxies`     | boolean string | `"true"` or `"false"`                      |
| `verified`    | boolean string | `"true"` or `"false"`                      |

<Warning>
  Boolean query values must be exact strings: `"true"` or `"false"`.
</Warning>

## Available tools

<Accordion title="navigate">
  Navigate to any URL in the browser

  <ParamField path="url" type="string" required>
    The URL to navigate to
  </ParamField>
</Accordion>

<Accordion title="act">
  Perform an action on the web page using natural language

  <ParamField path="action" type="string" required>
    The action to perform (e.g., "click the login button", "fill form field")
  </ParamField>
</Accordion>

<Accordion title="observe">
  Observe and find actionable elements on the page.

  <ParamField path="instruction" type="string" required>
    Specific instruction for observation (e.g., "find the login button", "locate search form")
  </ParamField>
</Accordion>

<Accordion title="extract">
  Extract data from the current page.

  <ParamField path="instruction" type="string">
    Optional extraction instruction.
  </ParamField>
</Accordion>

<Accordion title="start">
  Create or reuse a Browserbase session and set it as active for the current MCP transport session.

  **Inputs**

  <Info>No input parameters required.</Info>

  **Output**

  <ResponseField name="sessionId" type="string">
    Browserbase session ID.
  </ResponseField>
</Accordion>

<Accordion title="end">
  Close the active Browserbase session for the current MCP transport session.

  <Info>No input parameters required.</Info>
</Accordion>

## Local command-line flags

<Note>
  Command-line flags are only available when running the server locally (`npx @browserbasehq/mcp` with flags or local development setup).
</Note>

| Flag                       | Description                                                                                                                                          |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--proxies`                | Enable Browserbase proxies for the session                                                                                                           |
| `--verified`               | Enable Browserbase Verified (Scale Plan only)                                                                                                        |
| `--keepAlive`              | Enable Browserbase Keep Alive Session                                                                                                                |
| `--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 or [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) 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)                                                                                                        |

## Installation methods

<Tabs>
  <Tab title="Hosted (recommended)">
    Use your MCP client config:

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "url": "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY"
        }
      }
    }
    ```

    For custom models, include `modelName` and `modelApiKey`:

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "url": "https://mcp.browserbase.com/mcp?browserbaseApiKey=YOUR_BROWSERBASE_API_KEY&modelName=openai/gpt-4.1&modelApiKey=YOUR_MODEL_API_KEY"
        }
      }
    }
    ```
  </Tab>

  <Tab title="NPM Package (STDIO)">
    The easiest way to get started locally is using the NPM package.

    <Note>
      If you'd like to use a different model, pass the model name and keys in the args. More info [here](#local-command-line-flags).
    </Note>

    <Steps>
      <Step title="Add to MCP config">
        Go into your MCP Config JSON and add the Browserbase Server:

        <CodeGroup>
          ```json Claude Desktop theme={null}
          {
            "mcpServers": {
              "browserbase": {
                "command": "npx",
                "args": ["@browserbasehq/mcp"],
                "env": {
                  "BROWSERBASE_API_KEY": "your_api_key",
                  "GEMINI_API_KEY": "your_gemini_api_key"
                }
              }
            }
          }
          ```
        </CodeGroup>
      </Step>

      <Step title="Restart your MCP client">
        <Check>
          That's it! Reload your MCP client and you'll be able to use Browserbase.
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Local Development">
    For local development or customization, you can run the server locally.

    <Steps>
      <Step title="Clone and build">
        ```bash theme={null}
        # 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
        ```
      </Step>

      <Step title="Choose your transport method">
        You can run locally using either STDIO or [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).

        <Tabs>
          <Tab title="STDIO">
            Add the following to your MCP Config JSON file:

            ```json theme={null}
            {
              "mcpServers": {
                "browserbase": {
                  "command": "node",
                  "args": ["/path/to/mcp-server-browserbase/cli.js"],
                  "env": {
                    "BROWSERBASE_API_KEY": "your_api_key",
                    "GEMINI_API_KEY": "your_gemini_api_key"
                  }
                }
              }
            }
            ```
          </Tab>

          <Tab title="Self-hosted Streamable HTTP">
            First, run the server:

            ```bash theme={null}
            node cli.js --port 8931
            ```

            Then add this to your MCP Config JSON file:

            ```json theme={null}
            {
              "mcpServers": {
                "browserbase": {
                  "url": "http://localhost:8931/mcp",
                  "env": {
                    "BROWSERBASE_API_KEY": "your_api_key",
                    "GEMINI_API_KEY": "your_gemini_api_key"
                  }
                }
              }
            }
            ```
          </Tab>
        </Tabs>
      </Step>

      <Step title="Restart your client">
        <Check>
          Reload your MCP client and you should be good to go!
        </Check>
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Verify installation

<Steps>
  <Step title="Restart your MCP client">
    Restart/refresh your MCP client app and verify tools are available.
  </Step>

  <Step title="Test the integration">
    Get started by asking your MCP client to navigate to any page and see your Browserbase browser in action on the [dashboard](https://www.browserbase.com/sessions).

    <Tip>
      Try: "Navigate to example.com and extract the main heading"
    </Tip>
  </Step>
</Steps>

## Further reading

<CardGroup cols={3}>
  <Card title="Model Context Protocol (MCP) docs" icon="book" href="https://modelcontextprotocol.io/introduction">
    Learn more about the MCP protocol
  </Card>

  <Card title="Browserbase Documentation" icon="globe" href="https://docs.browserbase.com">
    Explore Browserbase features and capabilities
  </Card>

  <Card title="Support" icon="headset" href="mailto:support@browserbase.com">
    Get help from the Browserbase support team
  </Card>
</CardGroup>