Stagehand Server Local Mode

npm version License: Apache-2.0

Run Stagehand browser automation locally without cloud services. A fork of the official @browserbasehq/mcp-server-browserbase with LOCAL mode support.

Why This Fork?

The official Browserbase MCP server only supports cloud mode, requiring a paid Browserbase subscription. However, Stagehand itself fully supports local browser execution.

This fork unlocks that capability:

Feature	Official Version	This Fork
Browser execution	Browserbase Cloud only	Local Headless Chrome
Required credentials	BROWSERBASE_API_KEY + PROJECT_ID	Only LLM API key
Cost	Browserbase subscription	Free (bring your own LLM key)
Network requirement	Internet required	Works offline/intranet
Auto screenshots	❌	✅ After each action

Use Cases

• Local development - Test browser automation without cloud costs
• Self-hosted AI agents - Run on your own servers
• Air-gapped environments - No external cloud dependency
• CI/CD pipelines - Automated testing without cloud API limits

Quick Start

Using npx (Recommended)

npx stagehand-mcp-local

Add to Claude Code

claude mcp add stagehand-local \
  -e STAGEHAND_ENV=LOCAL \
  -e OPENAI_API_KEY=your_key \
  -- npx stagehand-mcp-local

Add to Cursor / VS Code

Add to your MCP configuration:

{
  "mcpServers": {
    "stagehand-local": {
      "command": "npx",
      "args": ["stagehand-mcp-local"],
      "env": {
        "STAGEHAND_ENV": "LOCAL",
        "OPENAI_API_KEY": "your_openai_key"
      }
    }
  }
}

Installation

npm (Global)

npm install -g stagehand-mcp-local

From Source

git clone https://github.com/weijiafu14/stagehand-mcp-local.git
cd stagehand-mcp-local
pnpm install
pnpm build

Configuration

Environment Variables

Variable	Description	Default	Required
STAGEHAND_ENV	Set to LOCAL for local mode	BROWSERBASE	Yes
OPENAI_API_KEY	OpenAI API key	-	One of these
GEMINI_API_KEY	Google Gemini API key	-	is required
ANTHROPIC_API_KEY	Anthropic API key	-	for Stagehand
HEADLESS	Run browser headless	true	No
SCREENSHOT_ENABLED	Enable auto screenshots	true	No
SCREENSHOT_DIR	Screenshot save directory	/tmp/stagehand-screenshots	No

CLI Options

All original Browserbase MCP server options are supported:

npx stagehand-mcp-local --browserWidth 1920 --browserHeight 1080 --experimental

Flag	Description
--browserWidth <width>	Browser viewport width (default: 1024)
--browserHeight <height>	Browser viewport height (default: 768)
--modelName <model>	LLM model for Stagehand (default: gemini-2.0-flash)
--experimental	Enable experimental Stagehand features

Available MCP Tools

Once connected, your AI assistant can use these tools:

Tool	Description
browserbase_session_create	Create a new browser session
browserbase_session_close	Close the current session
browserbase_stagehand_navigate	Navigate to a URL
browserbase_stagehand_act	Perform actions (click, type, etc.)
browserbase_stagehand_extract	Extract data from page
browserbase_stagehand_observe	Find interactive elements
browserbase_screenshot	Take a screenshot
browserbase_stagehand_agent	Run autonomous agent task

Auto Screenshots

In LOCAL mode, screenshots are automatically captured after each action for debugging and visualization:

Action performed: Click the login button
[SCREENSHOT:/tmp/stagehand-screenshots/default/1702012345678.jpg]

Parse the screenshot path programmatically:

const match = output.match(/\[SCREENSHOT:(.+?)\]/);
if (match) {
  const screenshotPath = match[1];
  // Use the screenshot...
}

System Requirements

macOS / Windows

Playwright will download Chromium automatically.

Linux (Ubuntu/Debian)

# Install browser dependencies
apt-get update && apt-get install -y \
  chromium libatk1.0-0 libatk-bridge2.0-0 libcups2 \
  libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
  libxfixes3 libxrandr2 libgbm1 libasound2 \
  libpango-1.0-0 libcairo2

# Install Playwright browsers
npx playwright install chromium

Docker

FROM node:20

RUN apt-get update && apt-get install -y \
  chromium libatk1.0-0 libatk-bridge2.0-0 libcups2 \
  libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 \
  libxfixes3 libxrandr2 libgbm1 libasound2 \
  libpango-1.0-0 libcairo2 \
  && rm -rf /var/lib/apt/lists/*

ENV PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
RUN npx playwright install chromium

ENV STAGEHAND_ENV=LOCAL

Switching Between Modes

You can switch back to Browserbase cloud mode anytime:

{
  "env": {
    "STAGEHAND_ENV": "BROWSERBASE",
    "BROWSERBASE_API_KEY": "your_key",
    "BROWSERBASE_PROJECT_ID": "your_project_id",
    "GEMINI_API_KEY": "your_gemini_key"
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Credits

This project is a fork of @browserbasehq/mcp-server-browserbase by Browserbase, Inc.

Built with:

• Stagehand - AI browser automation framework
• Model Context Protocol - LLM integration standard
• Playwright - Browser automation

License

Apache-2.0 - See LICENSE for details.

Original work: Copyright 2025 Browserbase, Inc. Modifications: Copyright 2025 weijiafu14