Browserbase MCP Server for Claude Code: Setup & Config

What you can do with Browserbase in Claude Code

Use a compact browser toolset with a hosted starting point and configurable self-hosted alternative.

• Run a browser session from an assistant without managing a local browser.
• Extract page data through Stagehand-backed automation.

Before you start: Browserbase in Claude Code

• An MCP-compatible client
• npx for local npm execution
• Browserbase credentials and a model key for self-hosted execution

The command is the self-hosted stdio option. The remote URL uses Streamable HTTP and is the README's recommended setup. Self-hosted custom models use --modelName and --modelApiKey.

Browserbase Claude Code configuration

1. Choose Claude Code configuration scope

   For Browserbase MCP Server, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add Browserbase MCP Server to Claude Code

   Use the mcp-server-browserbase entry below in mcpServers. Keep Browserbase MCP Server's documented stdio connection fields and your other Claude Code entries.

3. Check Browserbase MCP Server in Claude Code

   Browserbase MCP Server: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "mcp-server-browserbase": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@browserbasehq/mcp"
      ],
      "env": {
        "BROWSERBASE_API_KEY": "<your Browserbase API key>",
        "BROWSERBASE_PROJECT_ID": "<your Browserbase project ID>",
        "GEMINI_API_KEY": "<your Gemini API key for the default model>"
      }
    }
  }
}

claude mcp add-json --scope project 'mcp-server-browserbase' '{"type":"stdio","command":"npx","args":["@browserbasehq/mcp"],"env":{"BROWSERBASE_API_KEY":"<your Browserbase API key>","BROWSERBASE_PROJECT_ID":"<your Browserbase project ID>","GEMINI_API_KEY":"<your Gemini API key for the default model>"}}'

Browserbase tools available to Claude Code

Browserbase's stored tool list documents 6 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

start

For Browserbase's start, review the permission request and arguments in Claude Code before approval.

Create a Browserbase session or reuse an existing one.

end

For Browserbase's end, review the permission request and arguments in Claude Code before approval.

Close the active Browserbase session.

navigate

For Browserbase's navigate, review the permission request and arguments in Claude Code before approval.

act

For Browserbase's act, review the permission request and arguments in Claude Code before approval.

observe

For Browserbase's observe, review the permission request and arguments in Claude Code before approval.

Identify page elements relevant to an interaction instruction.

extract

For Browserbase's extract, review the permission request and arguments in Claude Code before approval.

Browserbase: full stored tool descriptions

Troubleshooting Browserbase in Claude Code

• If Browserbase MCP Server fails to start, check npx @browserbasehq/mcp (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• Browserbase MCP Server: check BROWSERBASE_API_KEY, BROWSERBASE_PROJECT_ID, GEMINI_API_KEY; keep credentials out of shared .mcp.json.
• Browserbase MCP Server uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Self-hosted setup requires Browserbase credentials and model authentication.
• Known limitation: Custom models require a separate provider key.
• Known limitation: Verified Identity is restricted to Scale plan users.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions