Package Exports

stagehand-mcp
stagehand-mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (stagehand-mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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