Skip to content
Puppeteer MCP Logo Puppeteer MCP

Puppeteer MCP Documentation

Puppeteer MCP Documentation

Section titled “Puppeteer MCP Documentation”

Version: 1.0.11
Status: Beta - Seeking Production Feedback
Type: Documentation Hub
Audience: Developers, Users, Contributors

Welcome to the comprehensive documentation for Puppeteer MCP - a beta AI-enabled browser automation platform that provides REST, gRPC, WebSocket, and Model Context Protocol (MCP) interfaces with unified session management, enterprise-focused security, and comprehensive Puppeteer integration.

🔔 Beta Release - Feedback Needed!
This project is in beta and we’re actively seeking user feedback to ensure it meets production requirements. Please report issues or share your experience to help us improve.

🚀 Quick Navigation

Section titled “🚀 Quick Navigation”

🚀 Getting Started

New to Puppeteer MCP? Start here for a quick setup guide.

Quick Start Guide →

🔌 API Reference

Complete API documentation for all supported protocols.

API Documentation →

🤖 Browser Automation

Learn how to automate browsers with our Puppeteer integration.

Automation Guide →

🛡️ Security

NIST-compliant security architecture and best practices.

Security Documentation →

📋 What is Puppeteer MCP?

Section titled “📋 What is Puppeteer MCP?”

Puppeteer MCP is a beta platform that bridges AI agents and browser automation through multiple protocol interfaces. We’re seeking feedback to ensure production readiness. It enables:

  • AI-Driven Browser Control: LLMs can control browsers through the Model Context Protocol
  • Multi-Protocol Support: Choose between REST, gRPC, WebSocket, or MCP interfaces
  • Enterprise Security: NIST 800-53r5 compliant with comprehensive authentication
  • Unified Sessions: Consistent session management across all protocols
  • Resource Management: Production-grade browser pooling and lifecycle management

🎯 Key Features

Section titled “🎯 Key Features”

Browser Automation

Section titled “Browser Automation”
  • 13 Action Types: Navigate, click, type, screenshot, evaluate JavaScript, and more
  • Security Sandbox: XSS prevention and input validation
  • Resource Pooling: Efficient browser instance management
  • Event Streaming: Real-time browser events via WebSocket

Protocol Support

Section titled “Protocol Support”
  • REST API: OpenAPI 3.0 compliant with comprehensive endpoints
  • gRPC: High-performance binary protocol with streaming
  • WebSocket: Real-time bidirectional communication
  • MCP: AI agent integration with standardized tools

Security & Compliance

Section titled “Security & Compliance”
  • NIST 800-53r5: Full compliance with tagged controls
  • Multi-Modal Auth: JWT tokens and API keys
  • Audit Logging: Complete security event tracking
  • Zero Trust: All requests authenticated and authorized

Developer Experience

Section titled “Developer Experience”
  • TypeScript: 100% type-safe with zero compilation errors
  • Testing: Comprehensive test suite with 283 tests
  • Standards: Follows William Zujkowski’s coding standards
  • Documentation: Progressive disclosure with AI optimization

🔍 Use Cases

Section titled “🔍 Use Cases”

🧪 E2E Testing : AI-guided browser testing with natural language commands

🌐 Web Scraping : Intelligent data extraction with browser automation

📸 Visual Testing : Automated screenshot comparison and regression testing

🔌 API Testing : Browser-based API testing with full network control

📚 Documentation Structure

Section titled “📚 Documentation Structure”

Our documentation follows the Knowledge Management Standards with progressive disclosure:

For New Users

Section titled “For New Users”
  1. Getting Started Guide - Set up and run your first automation
  2. API Quick Reference - Common API patterns
  3. MCP Usage Examples - AI agent integration examples

For Developers

Section titled “For Developers”
  1. Architecture Overview - System design and components
  2. Development Workflow - Build, test, and contribute
  3. API Integration Guide - Deep dive into protocols

For Contributors

Section titled “For Contributors”
  1. Contributing Guidelines - How to contribute
  2. Coding Standards - Code quality requirements
  3. Testing Guide - Testing strategies and coverage

🛠️ Quick Start

Section titled “🛠️ Quick Start”

Installation

Section titled “Installation”
Terminal window
# Clone the repository
git clone https://github.com/williamzujkowski/puppeteer-mcp.git
cd puppeteer-mcp


# Install dependencies
npm install


# Run in development mode
npm run dev

Basic Usage

Section titled “Basic Usage”
Terminal window
# Create a browser context
curl -X POST http://localhost:8443/api/v1/contexts \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-browser"}'


# Navigate to a page
curl -X POST http://localhost:8443/api/v1/contexts/{id}/execute \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"action": "navigate", "params": {"url": "https://example.com"}}'
{
  "tool": "create-context",
  "arguments": {
    "name": "test-browser",
    "options": {
      "viewport": {
        "width": 1920,
        "height": 1080
      }
    }
  }
}

🔗 Quick Links

Section titled “🔗 Quick Links”

📊 Project Status

Section titled “📊 Project Status”