browserbase-session-debugger

MCP server for debugging completed Browserbase sessions. Inspect CDP logs, rrweb recordings, DOM snapshots, and network activity from past browser runs.

What is this?

This is a post-run forensics tool — not for controlling live browsers. The official @browserbasehq/mcp-server-browserbase handles live browser control via Stagehand. This tool is for investigating what happened in sessions that already completed (or failed).

Use cases:

• "Why did my automation session fail?"
• "What did the DOM look like when the selector couldn't be found?"
• "Show me all network failures in this session"
• "Compare this failing session to the one that worked yesterday"

Setup

Add to your MCP client config (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "browserbase-debug": {
      "command": "npx",
      "args": ["-y", "browserbase-session-debugger"],
      "env": {
        "BROWSERBASE_API_KEY": "<your-api-key>",
        "BROWSERBASE_PROJECT_ID": "<your-project-id>",
        "STAGEHAND_MODEL_API_KEY": "<model-provider-key>"
      }
    }
  }
}

Get your API key and project ID from the Browserbase dashboard.

STAGEHAND_MODEL_API_KEY is only required for the get_replay_session_metrics and get_session_ai_summary tools. Use the model-provider key matching whichever LLM the original Stagehand run used — supported providers include OpenAI, Anthropic, Google Gemini, Vertex AI, Azure, Cerebras, DeepSeek, Groq, Mistral, Ollama, Perplexity, TogetherAI, xAI, Bedrock, and Cohere. See the Stagehand replay docs and model providers.

Remote (Streamable HTTP)

If you're hosting the server remotely (e.g., on a VPS, Railway, Fly.io), users can connect via URL with no local installation:

{
  "mcpServers": {
    "browserbase-debug": {
      "url": "https://your-server.com/mcp"
    }
  }
}

To start the server in HTTP mode:

BROWSERBASE_API_KEY=<key> BROWSERBASE_PROJECT_ID=<id> node build/index.js --http
# or
TRANSPORT=http PORT=3000 node build/index.js

Local development

{
  "mcpServers": {
    "browserbase-debug": {
      "command": "node",
      "args": ["/path/to/browserbase-session-debugger/build/index.js"],
      "env": {
        "BROWSERBASE_API_KEY": "<your-api-key>",
        "BROWSERBASE_PROJECT_ID": "<your-project-id>",
        "STAGEHAND_MODEL_API_KEY": "<model-provider-key>"
      }
    }
  }
}

Tools

Core

| Tool | Description | |------|-------------| | list_sessions | List sessions filtered by status (ERROR, TIMED_OUT, COMPLETED, RUNNING) and/or metadata query | | get_session_details | Get full details of a specific session | | get_session_logs | Get Chrome DevTools Protocol logs, optionally filtered by domain (Network, Console, Page, Runtime, DOM) | | get_session_recording | Get rrweb recording summary (event counts, time range, snapshots) | | get_session_downloads | Check if a session has downloaded files (served as ZIP) |

Smart Analysis

| Tool | Description | |------|-------------| | get_session_errors | Extract all errors: JS exceptions, console errors, network failures | | get_network_log | HAR-lite view of all network requests with status, timing, and size | | get_dom_snapshot | Reconstruct DOM state at any point in the recording | | compare_sessions | Side-by-side diff of two sessions (events, errors, network URLs) |

Stagehand Integration

| Tool | Description | |------|-------------| | get_stagehand_actions | Reconstruct Stagehand act/extract/observe/navigate calls from CDP logs with timing and parameters |

AI Replay Metrics

Backed by Stagehand's replay-metrics endpoint (alpha). Requires STAGEHAND_MODEL_API_KEY.

| Tool | Description | |------|-------------| | get_replay_session_metrics | Per-action LLM token usage, cost, duration, parameters, and results — inspect the agent's train of thought and debug AI fallbacks. Supports verbose and filter_method | | get_session_ai_summary | High-level totals (tokens, cost, LLM time), breakdown by method, slowest and most expensive actions — fast triage |

Example prompts

• "Show me all failed sessions"
• "What errors happened in session abc123?"
• "Get the network log for session abc123, only show failures"
• "What did the DOM look like at the end of session abc123?"
• "Compare session abc123 with session def456 — what changed?"
• "Show me the Console logs from session abc123"
• "What Stagehand actions were performed in session abc123?"
• "Show me the detailed Stagehand timeline for session abc123"
• "What did the Stagehand AI think while running session abc123?"
• "How much did session abc123 cost in tokens?"
• "Which Stagehand actions were the slowest in session abc123?"

Requirements

• Node.js 18+
• Browserbase account with API key

Building from source

npm install
npm run build

License

MIT