stage-hand-local-mcp

btree1970/stage-hand-local-mcp

3.2

If you are the rightful owner of stage-hand-local-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server for AI-powered browser automation that runs 100% locally on your machine.

Tools
5
Resources
0
Prompts
0

MCP Server Local Browser

A Model Context Protocol (MCP) server for AI-powered browser automation that runs 100% locally on your machine. Built with Stagehand and Playwright.

Features

  • 🖥️ 100% Local: Runs Chrome/Chromium directly on your machine
  • 🤖 AI-Powered: Natural language browser automation using Stagehand
  • 🚀 Fast: No cloud latency, everything runs locally
  • 🔒 Private: Your data never leaves your machine
  • 🎯 MCP Compatible: Works with Claude Desktop, Cursor, and other MCP clients

Prerequisites

  • Node.js 18 or higher
  • Chrome or Chromium browser
  • An AI model API key (choose one):
    • Google Gemini API key (recommended)
    • OpenAI API key
    • Anthropic API key

Installation

From npm (coming soon)

npm install -g mcp-server-local-browser

From source

git clone https://github.com/yourusername/mcp-server-local-browser.git
cd mcp-server-local-browser
pnpm install
pnpm build
pnpm playwright install chromium

Configuration

Claude Code (VSCode Extension)

Add the server using the Claude Code command palette:

claude mcp add browser /path/to/mcp-server-local-browser/cli.js --env GEMINI_API_KEY=your-api-key-here

For example, if you've cloned this repo to your home directory:

claude mcp add browser ~/mcp-server-local-browser/cli.js --env GEMINI_API_KEY=AIzaSyD...your-key

You can also add additional options:

claude mcp add browser ~/mcp-server-local-browser/cli.js \
  --env GEMINI_API_KEY=your-api-key-here \
  --arg "--headless" \
  --arg "--width" --arg "1920" \
  --arg "--height" --arg "1080"

Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "browser": {
      "command": "npx",
      "args": ["mcp-server-local-browser"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

From source

{
  "mcpServers": {
    "browser": {
      "command": "node",
      "args": ["/path/to/mcp-server-local-browser/cli.js"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

navigate

Navigate to any URL.

{
  "url": "https://example.com"
}

screenshot

Capture screenshots of the page or specific elements.

{
  "fullPage": true,        // Optional: capture full page
  "selector": "#element",  // Optional: capture specific element
  "name": "screenshot"     // Optional: name for the file
}

act

Perform actions using natural language.

{
  "action": "Click the login button and enter username 'john@example.com'"
}

extract

Extract structured data from pages.

{
  "instruction": "Extract all product names and prices"
}

observe

Get AI observations about the page content.

{
  "instruction": "Describe the main navigation menu"
}

CLI Options

mcp-local-browser [options]

Options:
  --headless              Run browser in headless mode
  --browser-path <path>   Path to Chrome/Chromium executable
  --user-data-dir <path>  Browser profile directory
  --width <width>         Viewport width (default: 1280)
  --height <height>       Viewport height (default: 720)
  --model-name <model>    AI model to use
  --model-api-key <key>   API key for the model
  --verbose <level>       Verbosity level 0-2 (default: 1)
  --debug-dom            Enable DOM debugging
  --enable-caching       Enable caching
  --experimental         Enable experimental features

Environment Variables

  • GEMINI_API_KEY: Google Gemini API key
  • OPENAI_API_KEY: OpenAI API key
  • ANTHROPIC_API_KEY: Anthropic API key

Examples

Basic Usage with Claude Desktop

Once configured, you can ask Claude:

  • "Navigate to GitHub and search for MCP servers"
  • "Take a screenshot of the current page"
  • "Click the sign in button"
  • "Extract all the links from this page"
  • "What's on this webpage?"

Using Custom Chrome Profile

To use your existing Chrome profile with saved cookies and extensions:

{
  "args": [
    "mcp-server-local-browser",
    "--user-data-dir",
    "/Users/you/Library/Application Support/Google/Chrome/Default"
  ]
}

Running in Headless Mode

For server environments or when you don't need to see the browser:

{
  "args": ["mcp-server-local-browser", "--headless"]
}

Development

# Install dependencies
pnpm install

# Build TypeScript
pnpm build

# Run tests
pnpm test

# Development mode with watch
pnpm watch

Architecture

The server uses:

  • Stagehand: AI-powered browser automation library
  • Playwright: Cross-browser automation
  • MCP SDK: Model Context Protocol implementation

Troubleshooting

Browser not found

Specify the Chrome path explicitly:

--browser-path "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"  # macOS
--browser-path "/usr/bin/google-chrome"  # Linux
--browser-path "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe"  # Windows

API Key issues

Ensure your API key is set in the environment or passed via CLI:

export GEMINI_API_KEY="your-key-here"
# or
mcp-local-browser --model-api-key "your-key-here"

Contributing

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

License

MIT

Credits

Built on top of: