Puppeteer MCP server

PuppeteerMCP Server is a powerful tool that implements the Model Context Protocol (MCP) to enable AI assistants to interact with web pages. Through this server, AI agents can navigate to URLs, capture screenshots at different viewport sizes, retrieve console logs, detect JavaScript errors, and perform various page interactions like clicking, typing, and scrolling.

Installation

Prerequisites

• Node.js 18+
• npm or yarn
• Chrome/Chromium browser (for Puppeteer)

Setup

# 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

Cursor Integration

To use this MCP server with Cursor:

1. Build the Server

npm run build

2. Configure Cursor

Add the MCP server to your Cursor configuration. The exact location depends on your OS:

• macOS: ~/.cursor/mcp.json
• Windows: %APPDATA%\Cursor\mcp.json
• Linux: ~/.config/cursor/mcp.json

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["/absolute/path/to/PuppeteerMCP/build/index.js"]
    }
  }
}

Important: Use the absolute path to your built JavaScript file.

3. Restart Cursor

Restart Cursor to load the MCP server. You should see the screenshot tool available in Cursor's AI interface.

Usage

Basic Screenshot Commands

In Cursor, you can request screenshots with commands like:

• "Take a screenshot of https://example.com"
• "Capture mobile and desktop screenshots of this website"
• "Show me how this page looks on different screen sizes"

Advanced Debugging Commands

• "Take a screenshot of my app and show me any JavaScript errors"
• "Debug this webpage - capture screenshots and check for console errors"
• "Screenshot this site and tell me about any network failures"

Screenshot Tool Features

Default Breakpoints

If no breakpoints are specified, the tool uses these standard responsive breakpoints:

• Mobile: 375px width (height auto-detected)
• Tablet: 768px width (height auto-detected)
• Desktop: 1280px width (height auto-detected)

Page Interaction Capabilities

The screenshot tool supports executing a sequence of page interactions before capturing screenshots:

Available Action Types:

• click - Click an element by CSS selector
• type - Type text into an input field
• clear - Clear an input field's value
• scroll - Scroll to coordinates or element
• hover - Hover over an element
• select - Select option from dropdown
• wait - Wait for specified duration
• waitForElement - Wait for element to appear
• navigate - Navigate to a different URL

Example Usage:

{
  "url": "https://example.com/login",
  "actions": [
    {
      "type": "type",
      "selector": "#username",
      "text": "[email protected]"
    },
    {
      "type": "type", 
      "selector": "#password",
      "text": "password123"
    },
    {
      "type": "click",
      "selector": "#login-button"
    },
    {
      "type": "waitForElement",
      "selector": ".dashboard",
      "timeout": 5000
    }
  ]
}

Error Reporting & Debugging

The screenshot tool captures and reports page activity:

• JavaScript Errors: Runtime errors with stack traces, line numbers, and sources
• Console Messages: All console.log(), console.warn(), console.error() output
• Network Issues: Failed requests (404s, 500s), CORS violations, timeouts
• Security Problems: CORS policy violations, blocked requests

Troubleshooting

Common Issues

Server not appearing in Cursor:

• Check the absolute path in your Cursor configuration
• Ensure the build/ directory exists and contains index.js
• Restart Cursor after configuration changes

Tool calls failing:

• Test the server with MCP inspector first
• Check console output for error messages
• Verify Puppeteer can launch browsers on your system

Browser launch failures:

• Install Chrome/Chromium if not present
• Set PUPPETEER_EXECUTABLE_PATH if using custom browser location
• Check for missing dependencies on Linux systems

Image Optimization

To ensure screenshots work well with Cursor's chat interface:

• Format: JPEG by default (80% quality) for smaller file sizes
• Width Limiting: Images wider than 1280px are automatically clipped
• Full Page Capture: Height is always full page content

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.