stagehand-mcp

Stagehand MCP Server

An MCP (Model Context Protocol) server that exposes Stagehand browser automation capabilities to Claude and other MCP clients.

Features

• Browser Automation: Navigate, click, type, and interact with web pages using natural language
• Data Extraction: Extract structured information from any webpage
• Screenshots: Capture page screenshots as base64 or save to files
• Local Browser: Uses your local Chrome/Chromium installation
• AI-Powered: Leverages OpenAI models for intelligent web interactions

Installation

MCP Configuration

Add to your MCP client configuration:

{
    "mcpServers": {
        "stagehand": {
            "command": "npx",
            "args": ["stagehand-mcp"],
            "env": {
                "OPENAI_API_KEY": "your-openai-api-key"
            }
        }
    }
}

Arguments

• --modelName - Override the default model (default: "openai/gpt-4.1-mini")
• --modelApiKey - Override the API key (default: OPENAI_API_KEY env var)
• --executablePath - Override browser executable path
• --headless - Run in headless mode
• --cdpUrl - Connect to an existing browser instance via Chrome DevTools Protocol URL
• --includeTokenMetrics - Include token usage metrics in AI-powered tool responses

Development

npm run dev        # Watch mode for development
npm run inspector  # Launch MCP Inspector for testing

Tools

The server provides 5 core automation tools:

• navigate - Navigate to URLs
• act - Perform actions using natural language (click, type, etc.)
• extract - Extract structured data from pages
• observe - Get information about actionable elements
• screenshot - Capture page screenshots

Extract Tool Usage

The extract tool can extract structured data from web pages using natural language instructions. You can optionally provide a JSON schema to specify the exact structure you want.

Basic Usage

Extract all product names and prices from this page

Schema-based Extraction

For structured data extraction, provide a JSON schema:

{
  "instruction": "extract product information",
  "schema": {
    "type": "object",
    "properties": {
      "products": {
        "type": "array",
        "items": {
          "type": "object", 
          "properties": {
            "name": { "type": "string" },
            "price": { "type": "string" },
            "url": { 
              "type": "string",
              "format": "uri"
            }
          }
        }
      }
    }
  }
}

Supported Schema Types

• string - Text data
• string with format: "uri" or format: "url" - URLs/links (validates as proper URLs)
• number - Numeric values
• boolean - True/false values
• array - Lists of items
• object - Nested structures

URL/Link Extraction

To extract URLs or links, use the format: "uri" specification:

{
  "type": "object",
  "properties": {
    "contactLink": {
      "type": "string",
      "format": "uri"
    }
  }
}

This ensures the extracted value is validated as a proper URL format.

Token Usage Tracking

When the --includeTokenMetrics flag is enabled, AI-powered tools (act, extract, observe) will include token usage data in their responses using the standard MCP usage field:

{
  "content": [
    {
      "type": "text",
      "text": "Action completed: click the login button"
    }
  ],
  "usage": {
    "input_tokens": 1250,
    "output_tokens": 830
  }
}

Configuration Example

{
  "mcpServers": {
    "stagehand": {
      "command": "npx",
      "args": ["stagehand-mcp", "--includeTokenMetrics"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}

How It Works

• Token metrics are tracked per tool call (not cumulative)
• Only AI-powered tools report token usage (navigate and screenshot do not use AI)
• Metrics show prompt tokens (input) and completion tokens (output) for each operation
• Data comes from Stagehand's built-in metrics tracking

License

MIT