Overview

The MCP Puppeteer Server enables AI models to control and interact with web browsers through Puppeteer, Google's powerful headless browser automation library. This server provides comprehensive browser automation capabilities for testing, scraping, and web interaction tasks.

Official Server (Archived):

Developed by Anthropic as part of the official MCP servers collection (now archived)

Key Features

🌐

Browser Navigation

Navigate to URLs, interact with pages, and control browser behavior

📸

Screenshot Capture

Capture full-page or element-specific screenshots in various formats

🖱️

Element Interaction

Click, hover, fill forms, and select options using CSS selectors

⚡

JavaScript Execution

Execute custom JavaScript code in the browser context

Available Tools

Quick Reference

Tool	Purpose	Category
`puppeteer_navigate`	Navigate to URL	Navigation
`puppeteer_screenshot`	Capture screenshots	Capture
`puppeteer_click`	Click elements	Interaction
`puppeteer_hover`	Hover over elements	Interaction
`puppeteer_fill`	Fill input fields	Forms
`puppeteer_select`	Select dropdown options	Forms
`puppeteer_evaluate`	Execute JavaScript	Scripting

Detailed Usage

puppeteer_navigate▶

Navigate to any URL and load the page in the browser.

// Basic navigation
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_navigate",
  arguments: {
    url: "https://example.com"
  }
});

// Navigation with custom launch options
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_navigate",
  arguments: {
    url: "https://example.com",
    launchOptions: {
      headless: true,
      args: ["--no-sandbox", "--disable-setuid-sandbox"]
    }
  }
});

Returns navigation result with page status.

puppeteer_screenshot▶

Capture screenshots of the entire page or specific elements.

// Full page screenshot
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_screenshot",
  arguments: {
    name: "homepage",
    width: 1920,
    height: 1080
  }
});

// Element-specific screenshot
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_screenshot",
  arguments: {
    name: "login-form",
    selector: "#login-container",
    width: 800,
    height: 600
  }
});

// Screenshot with encoding
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_screenshot",
  arguments: {
    name: "encoded-screenshot",
    width: 1280,
    height: 720,
    encoded: true  // Returns base64-encoded image
  }
});

Returns screenshot as PNG image or base64-encoded string.

puppeteer_click▶

Click on elements using CSS selectors.

// Click a button
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_click",
  arguments: {
    selector: "button.submit-btn"
  }
});

// Click a link
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_click",
  arguments: {
    selector: "a[href='/login']"
  }
});

Returns click confirmation and any navigation results.

puppeteer_hover▶

Hover over elements to trigger hover effects or reveal content.

use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_hover",
  arguments: {
    selector: ".dropdown-trigger"
  }
});

Useful for revealing dropdown menus or tooltips.

puppeteer_fill▶

Fill input fields, textareas, and other form elements.

// Fill text input
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_fill",
  arguments: {
    selector: "input[name='username']",
    value: "[email protected]"
  }
});

// Fill password field
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_fill",
  arguments: {
    selector: "input[type='password']",
    value: "SecurePassword123"
  }
});

// Fill textarea
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_fill",
  arguments: {
    selector: "textarea#comments",
    value: "This is a test comment"
  }
});

Clears existing content before filling the field.

puppeteer_select▶

Select options from dropdown menus (SELECT elements).

// Select by value
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_select",
  arguments: {
    selector: "select[name='country']",
    value: "US"
  }
});

// Select multiple options
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_select",
  arguments: {
    selector: "select[name='interests']",
    value: ["technology", "design", "engineering"]
  }
});

Supports single and multi-select dropdowns.

puppeteer_evaluate▶

Execute JavaScript code in the browser console and return results.

// Get page title
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: "document.title"
  }
});

// Extract data from the page
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: `
      Array.from(document.querySelectorAll('h1'))
        .map(h => h.textContent)
    `
  }
});

// Modify page content
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: `
      document.querySelector('#notification').style.display = 'none';
      return 'Notification hidden';
    `
  }
});

// Complex data extraction
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: `
      ({
        title: document.title,
        url: window.location.href,
        links: Array.from(document.querySelectorAll('a'))
          .map(a => ({ text: a.textContent, href: a.href })),
        images: Array.from(document.querySelectorAll('img'))
          .map(img => img.src)
      })
    `
  }
});

Returns the result of the JavaScript expression.

Available Resources

Console Logs

Access browser console output including logs, warnings, and errors:

console://logs

This resource provides real-time access to all console messages generated during browser automation.

Screenshots

Access captured screenshots by name:

screenshot://<name>

Screenshots are stored as PNG images and can be retrieved using the name specified during capture.

Installation

{
  "mcpServers": {
    "puppeteer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "DOCKER_CONTAINER=true",
        "mcp/puppeteer"
      ]
    }
  }
}

Headless Mode:

Docker installation runs in headless mode, ideal for server environments and automated testing.

Common Use Cases

1. Automated Testing Workflow

Automate end-to-end testing of web applications:

// Navigate to application
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_navigate",
  arguments: {
    url: "https://app.example.com/login"
  }
});

// Fill login form
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_fill",
  arguments: {
    selector: "input[name='email']",
    value: "[email protected]"
  }
});

use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_fill",
  arguments: {
    selector: "input[name='password']",
    value: "testpassword123"
  }
});

// Submit form
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_click",
  arguments: {
    selector: "button[type='submit']"
  }
});

// Verify successful login
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: "document.querySelector('.dashboard') !== null"
  }
});

// Capture screenshot of dashboard
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_screenshot",
  arguments: {
    name: "dashboard-after-login",
    width: 1920,
    height: 1080
  }
});

2. Web Scraping and Data Extraction

Extract structured data from websites:

// Navigate to target page
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_navigate",
  arguments: {
    url: "https://news.example.com"
  }
});

// Extract article data
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: `
      Array.from(document.querySelectorAll('.article')).map(article => ({
        title: article.querySelector('h2').textContent,
        author: article.querySelector('.author').textContent,
        date: article.querySelector('.date').textContent,
        excerpt: article.querySelector('.excerpt').textContent,
        url: article.querySelector('a').href
      }))
    `
  }
});

// Extract product prices
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: `
      Array.from(document.querySelectorAll('.product')).map(product => ({
        name: product.querySelector('.product-name').textContent,
        price: product.querySelector('.price').textContent,
        rating: product.querySelector('.rating').textContent,
        availability: product.querySelector('.stock-status').textContent
      }))
    `
  }
});

3. Form Automation and Submission

Automate complex form workflows:

// Navigate to form
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_navigate",
  arguments: {
    url: "https://example.com/contact"
  }
});

// Fill text inputs
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_fill",
  arguments: {
    selector: "input[name='name']",
    value: "John Doe"
  }
});

use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_fill",
  arguments: {
    selector: "input[name='email']",
    value: "[email protected]"
  }
});

// Select dropdown option
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_select",
  arguments: {
    selector: "select[name='subject']",
    value: "support"
  }
});

// Fill textarea
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_fill",
  arguments: {
    selector: "textarea[name='message']",
    value: "I need help with my account."
  }
});

// Click submit button
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_click",
  arguments: {
    selector: "button.submit"
  }
});

// Verify submission
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: "document.querySelector('.success-message').textContent"
  }
});

4. Screenshot and Visual Testing

Capture screenshots for visual regression testing:

// Navigate to page
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_navigate",
  arguments: {
    url: "https://example.com/landing"
  }
});

// Capture full page screenshot
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_screenshot",
  arguments: {
    name: "landing-page-desktop",
    width: 1920,
    height: 1080
  }
});

// Capture mobile viewport
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_screenshot",
  arguments: {
    name: "landing-page-mobile",
    width: 375,
    height: 667
  }
});

// Capture specific component
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_screenshot",
  arguments: {
    name: "header-component",
    selector: "header.main-header",
    width: 1920,
    height: 100
  }
});

// Capture after interaction
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_hover",
  arguments: {
    selector: ".dropdown-menu"
  }
});

use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_screenshot",
  arguments: {
    name: "dropdown-open",
    selector: ".dropdown-menu",
    width: 300,
    height: 400
  }
});

5. Dynamic Content Monitoring

Monitor and extract data from dynamic pages:

// Navigate to dynamic content page
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_navigate",
  arguments: {
    url: "https://example.com/dashboard"
  }
});

// Wait for dynamic content to load and extract
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: `
      new Promise(resolve => {
        setTimeout(() => {
          resolve({
            metrics: Array.from(document.querySelectorAll('.metric'))
              .map(m => ({
                label: m.querySelector('.label').textContent,
                value: m.querySelector('.value').textContent
              })),
            lastUpdated: document.querySelector('.last-updated').textContent
          });
        }, 2000);
      })
    `
  }
});

// Monitor changes over time
use_mcp_tool({
  server_name: "puppeteer",
  tool_name: "puppeteer_evaluate",
  arguments: {
    script: `
      document.querySelector('.realtime-counter').textContent
    `
  }
});

Best Practices

Use Specific Selectors: Prefer ID and class selectors over complex CSS paths for reliability
Wait for Elements: Use puppeteer_evaluate with promises to wait for dynamic content
Handle Errors Gracefully: Check element existence before interaction to avoid failures
Optimize Screenshot Sizes: Use appropriate dimensions to balance quality and file size
Clean Up Resources: Close browser instances when done to free system resources
Respect Rate Limits: Add delays between requests when scraping to avoid being blocked
Use Headless Mode: Docker installation is more efficient for automated workflows

Security Considerations

Important Security Warning:

This server can access local files and internal IP addresses. Only use it with trusted URLs and in secure environments.

Security Best Practices

Validate URLs: Only navigate to trusted, verified URLs
Sandbox Execution: Run in Docker containers for isolation
Limit Network Access: Use firewalls to restrict outbound connections
Avoid Sensitive Data: Don't use for pages containing sensitive credentials
Review Scripts: Audit any JavaScript executed via puppeteer_evaluate
Use HTTPS: Prefer secure connections to prevent data interception

Performance Tips

Reuse Browser Instances: Multiple operations can share the same browser session
Disable Unnecessary Features: Use launch options to disable images, CSS for faster loading
Set Timeouts: Configure reasonable timeouts to prevent hanging operations
Limit Viewport Size: Smaller viewports render faster
Use Headless Mode: Headless browsers consume fewer resources
Cache Resources: Enable caching for frequently accessed resources

Troubleshooting

Common Issues

Issue: Browser fails to launch

Ensure Chrome/Chromium is installed on your system
Check that you have sufficient system resources
Use Docker installation for consistent environment

Issue: Elements not found

Verify CSS selectors are correct
Wait for dynamic content to load before interacting
Check if elements are inside iframes (requires special handling)

Issue: Screenshots are blank

Ensure page has fully loaded before capturing
Check viewport size is appropriate for content
Verify element selector exists on the page

Issue: Forms not submitting

Confirm all required fields are filled
Check for client-side validation errors
Ensure submit button selector is correct

Limitations

Archived Status: This server is no longer actively maintained by Anthropic
No Mobile Emulation: Limited mobile device testing capabilities
Single Page Context: Each navigation creates a new page context
No Multi-Tab Support: Cannot manage multiple tabs simultaneously
Limited File Upload: File input handling may require custom solutions

Alternative Solutions

For continued support and enhanced features, consider:

Community Implementations: Various maintained forks available on GitHub
Playwright MCP: Alternative browser automation with similar capabilities
Selenium MCP: Cross-browser testing support
Custom Implementation: Build your own Puppeteer MCP server for specific needs

Sources

Perplexity AI MCP Server: Real-time Search & Reasoning for AI

Explore Perplexity AI MCP Server for real-time web search, advanced reasoning, and comprehensive research. Empower your AI with up-to-date information and detailed answers.

RabbitMQ MCP Server

RabbitMQ MCP server enables AI models to interact with RabbitMQ message brokers, providing capabilities for queue management, message operations, system monitoring, and broker administration through the RabbitMQ HTTP Management API.

Cloudflare MCP Server

Interact with Cloudflare services using natural language through the Model Context Protocol.

Puppeteer MCP Server