a2a mcpa2a mcp
Back to Catalog
mcp-server4

Puppeteer MCP Server

Official reference Model Context Protocol server using Puppeteer for browser automation, enabling AI agents like Claude to navigate web pages, fill forms, execute JavaScript, take screenshots, and interact with live web content securely.

Overview

The Puppeteer MCP Server is one of the original reference implementations provided by the Model Context Protocol team (under Anthropic's open-source efforts, now part of the Linux Foundation governance). It integrates Puppeteer — Google's headless Chrome automation library — as an MCP server, giving any MCP-compatible AI client (Claude Desktop/Code, Cursor, GitHub Copilot, etc.) the ability to perform real browser actions in a controlled, sandboxed environment.

Launched alongside MCP in late 2024, this server has become a cornerstone for agentic web interactions, allowing models to go beyond static data access to dynamic, interactive web manipulation without custom APIs or fragile scraping scripts.

Key Features

  • Full Browser Control: Launch new headless browsers or connect to existing Chrome instances (via --remote-debugging-port).
  • Core Tools: Navigate to URLs, click elements, type text, fill forms, extract content, execute custom JavaScript, wait for selectors/network events.
  • Screenshots & Visuals: Capture full-page or element-specific screenshots (returned as base64 or file references).
  • PDF Generation: Export current page as PDF for archiving or analysis.
  • Cookie & Auth Handling: Manage cookies, handle logins, maintain sessions across calls.
  • Multiple Transports: Supports Streamable HTTP, SSE for real-time feedback, and experimental WebSocket patterns.
  • Security Controls: Sandboxed execution, configurable timeouts, no file system access by default, optional allow-lists for domains.

The server exposes ~15–20 standardized tools following MCP's tool schema, with clear descriptions that agents can discover and invoke autonomously.

Installation & Quick Start

The easiest way is via npx (no install needed):

npx -y @modelcontextprotocol/server-puppeteer

Or Docker (recommended for production/isolation):

docker run -i --rm --init -e DOCKER_CONTAINER=true mcp/puppeteer

Add to your MCP client config (e.g., Claude or Cursor):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
    }
  }
}

Once running, prompt your AI: "Go to example.com, take a screenshot of the homepage, then click the login button and fill credentials..."

Use Cases

  • Web Research & Data Extraction: Agents scrape dynamic content, follow links, aggregate info from multiple sites.
  • Automated Testing & QA: Run end-to-end browser tests or validate UI behavior via natural language.
  • Form Filling & E-commerce: Simulate user journeys, add to cart, checkout flows for demos or monitoring.
  • Screenshot-Based Analysis: Capture pages for visual regression, accessibility checks, or content verification.
  • Multi-Step Workflows: Combine with other MCP servers (e.g., GitHub + Puppeteer) for hybrid agent tasks.

Community telemetry from 2026 shows Puppeteer MCP enabling 5–10× faster prototyping of browser-dependent agents compared to traditional Selenium/WebDriver integrations.

Advanced Tips & Common Pitfalls

  • Use headless: false + connect to existing Chrome for debugging visible sessions.
  • Set timeouts and retry policies in tool calls to handle flaky networks.
  • Pitfall: Running without sandbox — always use --no-sandbox only in trusted envs; prefer Docker isolation.
  • Enterprise-tip: Deploy behind a gateway with API key auth (many forks like sultannaufal/puppeteer-mcp-server add this).
  • For persistent sessions, use connect() mode with remote debugging port.
  • Test with simple commands first: "Navigate to https://example.com and screenshot the page."

Alternatives & Ecosystem

While the official repo was archived in some mirrors (community reports from late 2025), active forks and enhanced versions thrive:

  • sultannaufal/puppeteer-mcp-server (self-hosted + auth + Docker)
  • merajmehrabi/puppeteer-mcp-server (connect to existing windows)
  • code-craka/puppeteer-mcp (multi-deployment support)

For cloud/always-on needs, explore Browserless or Playwright-based MCP servers as complements.

The Puppeteer MCP server remains essential infrastructure for making AI agents truly web-capable in 2026. Start with npx today and watch your model browse the internet like a human.

Tags

puppeteermcpbrowser-automationweb-scrapingai-agenttypescriptnodejsclaudeanthropic