puppeteer-mcp

Puppeteer MCP

Version: 1.0.1
Last Updated: 2025-01-05
Status: Production
Type: Browser Automation Platform
Audience: Developers, AI Engineers, DevOps

Production-ready AI-enabled browser automation platform with REST, gRPC, WebSocket, and Model Context Protocol (MCP) interfaces, unified session management, and enterprise-grade security.

🚀 Quick Start

Install from npm

# Install globally
npm install -g puppeteer-mcp@1.0.1

# Or use with npx (no installation required)
npx puppeteer-mcp@1.0.1

Start the MCP Server

# Start MCP server (if installed globally)
puppeteer-mcp

# Or with npx
npx puppeteer-mcp@1.0.1

Integrate with Claude Desktop

# Add to Claude Desktop configuration
claude mcp add puppeteer-mcp

For detailed setup instructions, see Getting Started Guide.

🎯 Key Features

• 🤖 AI-Ready: Native MCP support for LLM browser control
• 🌐 Multi-Protocol: REST, gRPC, WebSocket, and MCP interfaces
• 🔒 Enterprise Security: NIST-compliant with zero-trust architecture
• 🎭 Full Puppeteer Integration: 13+ browser action types
• 📊 Production Grade: Resource pooling, health monitoring, metrics
• 🚀 High Performance: Sub-100ms API response times

📋 Prerequisites

• Node.js 20+ and npm
• Chrome/Chromium (automatically downloaded by Puppeteer if not present)

🛠️ Installation Options

From Source

# Clone the repository
git clone https://github.com/williamzujkowski/puppeteer-mcp.git
cd puppeteer-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

💻 Usage Examples

REST API

# Create a browser context
curl -X POST http://localhost:3000/api/v1/contexts \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-browser"}'

# Navigate to a URL
curl -X POST http://localhost:3000/api/v1/contexts/{contextId}/execute \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "navigate",
    "params": {"url": "https://example.com"}
  }'

MCP with Claude

Once connected to Claude Desktop, you can use browser automation tools:

• execute-in-context - Execute browser actions (navigate, click, type, etc.)
• create-context - Create new browser contexts
• list-contexts - List active browser contexts

For detailed MCP usage examples, see MCP Usage Guide.

Configuration

Create a .env file in the project root:

# Server Configuration
PORT=3000
NODE_ENV=production

# Authentication
JWT_SECRET=your-secret-key
JWT_EXPIRY=15m
REFRESH_TOKEN_EXPIRY=7d

# Browser Configuration
PUPPETEER_HEADLESS=true
BROWSER_POOL_MAX_SIZE=5
BROWSER_IDLE_TIMEOUT=300000

# Security
RATE_LIMIT_WINDOW_MS=60000
RATE_LIMIT_MAX_REQUESTS=100

📚 Documentation

Quick Links

• Getting Started - Quick setup guide
• API Integration - Working with all protocols
• Browser Automation - Puppeteer actions guide
• Security Guide - NIST compliance and authentication
• Deployment Guide - Production deployment

API References

• REST API
• gRPC Services
• WebSocket Protocol
• MCP Tools
• Puppeteer Actions

🔧 Development

# Install dependencies
npm install

# Development commands
npm run dev          # Start with hot reload
npm test            # Run tests
npm run typecheck   # Type checking
npm run lint        # Linting
npm run check       # Run all checks

For detailed development workflow, see Development Guide.

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

This project follows William Zujkowski's Standards:

• TypeScript strict mode, max 300 lines/file
• 85%+ test coverage
• NIST security compliance

🚢 Deployment

Docker

# Build and run
docker build -t puppeteer-mcp .
docker run -p 3000:3000 -p 50051:50051 -e JWT_SECRET=your-secret puppeteer-mcp

For production deployment, see Deployment Guide.

🔒 Security

• Zero Trust Architecture
• NIST SP 800-53r5 compliant
• JWT + API key authentication
• Input validation on all endpoints

See Security Guide for details.

📄 License

Apache License 2.0 - see LICENSE file for details.

🆘 Support

• npm Package: npmjs.com/package/puppeteer-mcp
• Issues: GitHub Issues
• Security: See Security Guide for reporting vulnerabilities

Built with Puppeteer and Model Context Protocol

Changelog

[1.0.7] - 2025-01-05

Fixed

• Fixed express-rate-limit validation error about trust proxy setting
• Added configurable TRUST_PROXY environment variable
• Trust proxy now defaults to 'loopback' in development (only trust localhost)
• Disabled rate limit validation warning since we handle trust proxy properly

Added

• Added root route (/) that returns service information and available endpoints
• Added TRUST_PROXY configuration option for production deployments

Security

• Improved IP spoofing protection by making trust proxy configurable
• Better security for rate limiting in production environments