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

# Browserbase MCP 服务器配置

> 通过命令行标志、环境变量和高级选项配置浏览器自动化

## 配置概览

Browserbase MCP 服务器支持通过命令行标志和环境变量进行广泛配置。可自定义浏览器行为、代理设置、隐身模式、模型选择等参数，以适配您的浏览器自动化工作流。

<Note>
  命令行标志仅在本地运行服务器时可用（使用 `npx @browserbasehq/mcp` 加标志或本地开发环境）。
</Note>

## 环境变量

配置 Browserbase 核心凭证及可选调试设置：

<CardGroup cols={2}>
  <Card title="BROWSERBASE_API_KEY" icon="key">
    用于身份验证的 Browserbase API 密钥
  </Card>

  <Card title="BROWSERBASE_PROJECT_ID" icon="key">
    您的 Browserbase 项目 ID
  </Card>
</CardGroup>

## 命令行标志

### 可用标志

| 标志                         | 说明                                          |
| -------------------------- | ------------------------------------------- |
| `--proxies`                | 为会话启用 Browserbase 代理                        |
| `--advancedStealth`        | 启用 Browserbase 高级隐身模式（仅限 Scale 套餐）          |
| `--contextId <contextId>`  | 指定要使用的 Browserbase 上下文 ID                   |
| `--persist [boolean]`      | 是否持久化 Browserbase 上下文（默认值：true）             |
| `--port <port>`            | HTTP/SHTTP 传输监听的端口号                         |
| `--host <host>`            | 服务器绑定的主机地址（默认：localhost，使用 0.0.0.0 可监听所有接口） |
| `--cookies [json]`         | 要注入浏览器的 JSON 格式 cookie 数组                   |
| `--browserWidth <width>`   | 浏览器视口宽度（默认值：1024）                           |
| `--browserHeight <height>` | 浏览器视口高度（默认值：768）                            |
| `--modelName <model>`      | Stagehand 使用的模型（默认值：gemini-2.0-flash）       |
| `--modelApiKey <key>`      | 自定义模型提供商的 API 密钥（使用自定义模型时必需）                |

## 配置示例

### 基础配置

<Tabs>
  <Tab title="远程 URL (SHTTP)">
    <CodeGroup>
      ```json 直接 SHTTP theme={null}
      {
        "mcpServers": {
          "browserbase": {
            "url": "your-smithery-url.com"
          }
        }
      }
      ```
    </CodeGroup>

    使用我们远程托管的服务器时，我们会承担 Gemini 的 LLM 成本，这是 [Stagehand](https://www.stagehand.dev) 中[性能最佳的模型](https://www.stagehand.dev/evals)。
  </Tab>

  <Tab title="NPM 包">
    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "command": "npx",
          "args": ["@browserbasehq/mcp"],
          "env": {
            "BROWSERBASE_API_KEY": "your_api_key",
            "BROWSERBASE_PROJECT_ID": "your_project_id",
            "GEMINI_API_KEY": "your_gemini_api_key"
          }
        }
      }
    }
    ```
  </Tab>

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

  <Tab title="本地 SHTTP">
    ```bash theme={null}
    # 启动服务器
    node cli.js --port 8931
    ```

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

### 高级功能

<Tabs>
  <Tab title="代理">
    启用 Browserbase 代理实现 IP 轮换和地理位置测试。

    <Panel>
      [详细了解 Browserbase 代理](https://docs.browserbase.com/features/proxies)
    </Panel>

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "command": "npx",
          "args": ["@browserbasehq/mcp", "--proxies"],
          "env": {
            "BROWSERBASE_API_KEY": "your_api_key",
            "BROWSERBASE_PROJECT_ID": "your_project_id",
            "GEMINI_API_KEY": "your_gemini_api_key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="高级隐身">
    启用高级反检测功能增强隐身浏览体验。

    <Panel>
      [详细了解高级隐身模式](https://docs.browserbase.com/features/stealth-mode#advanced-stealth-mode)

      **注意：** 高级隐身功能仅限 Scale 套餐用户使用。
    </Panel>

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "command": "npx",
          "args": ["@browserbasehq/mcp", "--advancedStealth"],
          "env": {
            "BROWSERBASE_API_KEY": "your_api_key",
            "BROWSERBASE_PROJECT_ID": "your_project_id",
            "GEMINI_API_KEY": "your_gemini_api_key"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="上下文">
    使用持久化浏览器上下文维持会话间的认证状态。

    <Panel>
      [详细了解 Browserbase 上下文](https://docs.browserbase.com/features/contexts)
    </Panel>

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "command": "npx",
          "args": ["@browserbasehq/mcp", "--contextId", "your_context_id"],
          "env": {
            "BROWSERBASE_API_KEY": "your_api_key",
            "BROWSERBASE_PROJECT_ID": "your_project_id"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### 浏览器自定义

<Tabs>
  <Tab title="视口尺寸">
    自定义浏览器窗口尺寸。默认值为1024x768。推荐宽高比：16:9。

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "command": "npx",
          "args": [
            "@browserbasehq/mcp",
            "--browserWidth", "1920",
            "--browserHeight", "1080"
          ],
          "env": {
            "BROWSERBASE_API_KEY": "your_api_key",
            "BROWSERBASE_PROJECT_ID": "your_project_id",
            "GEMINI_API_KEY": "your_gemini_api_key"
          }
        }
      }
    }
    ```

    **常用分辨率：**

    * 桌面端：1920x1080、1280x720、1024x768
    * 移动端：375x667 (iPhone)、360x640 (Android)
    * 平板：768x1024 (iPad)
  </Tab>

  <Tab title="Cookie注入">
    注入会话Cookie以实现身份验证。当持久化上下文无法处理会话Cookie时特别有用。

    <Panel>
      Cookie必须符合[Playwright Cookie格式](https://playwright.dev/docs/api/class-browsercontext#browser-context-cookies)。
    </Panel>

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "command": "npx",
          "args": [
            "@browserbasehq/mcp",
            "--cookies",
            "[{\"name\": \"session\", \"value\": \"abc123\", \"domain\": \".example.com\", \"path\": \"/\", \"httpOnly\": true, \"secure\": true}]"
          ],
          "env": {
            "BROWSERBASE_API_KEY": "your_api_key",
            "BROWSERBASE_PROJECT_ID": "your_project_id",
            "GEMINI_API_KEY": "your_gemini_api_key"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 模型配置

为增强浏览器自动化功能配置AI模型。Stagehand默认使用Google的Gemini 2.0 Flash模型，但支持多种服务提供商。

<Warning>
  使用任何自定义模型（非默认模型）时，必须通过`--modelApiKey`参数提供该模型服务商的API密钥。
</Warning>

<Tabs>
  <Tab title="可用模型">
    **Google Gemini** (默认)

    * `google/gemini-2.0-flash` (默认)
    * `google/gemini-1.5-pro`
    * `google/gemini-1.5-flash`

    **OpenAI**

    * `openai/gpt-4o`
    * `openai/gpt-4o-mini`
    * `openai/o1-mini`
    * `openai/o1-preview`
    * `openai/o3-mini`

    **Anthropic Claude**

    * `anthropic/claude-3-5-sonnet-latest`
    * `anthropic/claude-3-7-sonnet-latest`

    [查看完整支持的模型列表](https://docs.stagehand.dev/examples/custom_llms#supported-llms)
  </Tab>

  <Tab title="配置示例">
    <CodeGroup>
      ```json OpenAI GPT-4o theme={null}
      {
        "mcpServers": {
          "browserbase": {
            "command": "npx",
            "args": [
              "@browserbasehq/mcp",
              "--modelName", "openai/gpt-4o",
              "--modelApiKey", "your_openai_api_key"
            ],
            "env": {
              "BROWSERBASE_API_KEY": "your_api_key",
              "BROWSERBASE_PROJECT_ID": "your_project_id"
            }
          }
        }
      }
      ```

      ```json Claude Sonnet theme={null}
      {
        "mcpServers": {
          "browserbase": {
            "command": "npx",
            "args": [
              "@browserbasehq/mcp",
              "--modelName", "anthropic/claude-3-5-sonnet-latest",
              "--modelApiKey", "your_anthropic_api_key"
            ],
            "env": {
              "BROWSERBASE_API_KEY": "your_api_key",
              "BROWSERBASE_PROJECT_ID": "your_project_id"
            }
          }
        }
      }
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 开发配置

<Tabs>
  <Tab title="调试模式">
    启用详细日志记录以进行故障排查和开发。

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "command": "npx",
          "args": ["@browserbasehq/mcp"],
          "env": {
            "BROWSERBASE_API_KEY": "your_api_key",
            "BROWSERBASE_PROJECT_ID": "your_project_id",
            "GEMINI_API_KEY": "your_gemini_api_key",
            "DEBUG": "true"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="自定义主机/端口">
    为SHTTP传输配置自定义主机和端口。

    ```json theme={null}
    {
      "mcpServers": {
        "browserbase": {
          "command": "npx",
          "args": [
            "@browserbasehq/mcp",
            "--host", "0.0.0.0",
            "--port", "8080"
          ],
          "env": {
            "BROWSERBASE_API_KEY": "your_api_key",
            "BROWSERBASE_PROJECT_ID": "your_project_id",
            "GEMINI_API_KEY": "your_gemini_api_key"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## 最佳实践

<Accordion title="性能 - 如何优化浏览器自动化性能？">
  * 根据使用场景选择合适的视口尺寸
  * 仅在需要地理位置定位时启用代理
  * 选择高效模型（Gemini Flash追求速度，GPT-4o追求准确度）
  * 复用上下文以保持身份验证持久性
</Accordion>

<Accordion title="安全 - 应实施哪些安全措施？">
  * 将API密钥安全存储在环境变量中
  * 敏感操作使用高级隐身模式
  * 实施正确的会话管理
  * 定期轮换cookies和上下文
</Accordion>

<Accordion title="开发 - 推荐哪些开发实践？">
  * 开发期间启用调试模式
  * 使用上下文持久化加速迭代
  * 测试不同视窗尺寸
  * 监控会话使用情况和配额
</Accordion>

<Accordion title="生产环境 - 如何配置生产环境？">
  * 使用NPM安装确保可靠性
  * 配置适当的超时时间
  * 实现错误处理和重试机制
  * 监控性能和资源使用情况
</Accordion>

## 延伸阅读

<CardGroup cols={3}>
  <Card title="Browserbase文档" icon="globe" href="https://docs.browserbase.com">
    完整平台文档
  </Card>

  <Card title="Stagehand文档" icon="robot" href="https://docs.stagehand.dev/">
    AI驱动的浏览器自动化
  </Card>

  <Card title="技术支持" icon="headset" href="mailto:support@browserbase.com">
    获取团队帮助
  </Card>
</CardGroup>