home / mcp / puppeteermcp server
An MCP server that provides Puppeteer-based screenshot tools for AI assistants with multi-breakpoint captures and rich metadata.
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.
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.
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.jsIf 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.
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.
Environment variables you may set to customize behavior include the browser path and environment mode. These relate to Puppeteer execution and server operation.
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.
Captures screenshots of web pages at multiple viewport breakpoints and returns structured metadata including viewport size, actual content size, load time, and error reports.