PuppeteerMCP Server

An MCP server that provides Puppeteer-based screenshot tools for AI assistants with multi-breakpoint captures and rich metadata.

javascript

7

GitHub Stars

javascript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "hushaudio-puppeteermcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/PuppeteerMCP/build/index.js"
      ],
      "env": {
        "NODE_ENV": "production",
        "PUPPETEER_EXECUTABLE_PATH": "<path-to-chromium-or-browser>"
      }
    }
  }
}

You run PuppeteerMCP to empower AI assistants with visual context of web pages. This MCP server exposes screenshot capabilities via the MCP protocol, letting you navigate to URLs, capture full-page screenshots at multiple viewport sizes, and receive structured metadata including errors, logs, and performance details. It supports both headless and headful browser modes and integrates smoothly with Cursor for AI-assisted development and debugging.

How to use

You use an MCP client to call the screenshot tool provided by PuppeteerMCP. The tool accepts a target URL and optional actions to perform before capturing screenshots. You can request mobile, tablet, and desktop breakpoints to see how a page renders across devices. The response includes the actual screenshots in a compact format along with a detailed activity report that highlights JavaScript errors, console messages, network issues, and other relevant page activity.

How to install

Prerequisites you need before installing: Node.js 18 or newer, npm or yarn, and a Chrome/Chromium browser for Puppeteer.

Install and prepare the server with these steps:

Clone the project and install dependencies

# Clone the repository
git clone <repository-url>
cd PuppeteerMCP

# Install dependencies
npm install

# Build the server
npm run build

# Test with MCP inspector
npx @modelcontextprotocol/inspector build/index.js

Additional setup after install

If you plan to use Cursor with this MCP server, you will typically run the built server using a standard stdio transport. The server is started as a local process and communicates with Cursor via input/output streams.

Usage in Cursor

In Cursor, configure the MCP server so it can be launched as a local process. After setup, you can ask Cursor to take screenshots of a page and view a comprehensive error and activity report inline in the chat.

Example usage patterns include taking screenshots of a site at multiple viewports, debugging JavaScript errors, and inspecting console output and network requests during page load.

Configuration notes

Environment variables you may set to customize behavior include the browser path and environment mode. These relate to Puppeteer execution and server operation.

Error handling and debugging

The server reports JavaScript errors, console messages, and network issues in a structured way. You receive a summary that includes counts of errors, warnings, and logs, plus a detailed breakdown by type with contextual information such as source, line numbers, and timestamps.

Available tools

screenshot

Captures screenshots of web pages at multiple viewport breakpoints and returns structured metadata including viewport size, actual content size, load time, and error reports.