What is Cursor Puppeteer Mcp

cursor-puppeteer-mcp is an MCP server designed for visual testing and feedback using Puppeteer. It allows users to automate interactions with web applications and capture visual results.

Use cases

Use cases include generating visual feedback for web components, validating UI changes after code modifications, and ensuring that web applications render correctly across different states.

How to use

To use cursor-puppeteer-mcp, you can either invoke it from the Cursor prompt after generating code or directly from the command line by providing a URL and optional parameters for actions and screenshots.

Key features

Key features include the ability to visit local development server URLs, check for errors, take screenshots of pages or specific elements, perform actions like clicking, and compare screenshots with expected results.

Where to use

cursor-puppeteer-mcp is ideal for web development, particularly in automated visual testing, UI validation, and feedback loops during the development process.

Cursor Puppeteer MCP

A Puppeteer-based MCP (Model-Control-Protocol) server for generating visual feedback to Cursor. This tool allows Cursor to:

1. Visit a local development server URL
2. Check for errors
3. Take screenshots of the page or specific elements
4. Perform actions like clicking on elements
5. Compare screenshots with expected results

Installation

npm install

How It Works

The MCP server communicates with Cursor using a specific protocol:

1. Cursor sends a URL and optional parameters to the MCP server
2. The server launches Puppeteer to visit the URL
3. Puppeteer performs any specified actions and takes screenshots
4. The server returns results to Cursor, including screenshot paths
5. Cursor can analyze the screenshots and delete them when they match the expected output

Usage

From Cursor

In your Cursor prompt, you can ask to use this tool at the end of code generation:

Generate a React counter component. After generating the code, use the Puppeteer tool to take a screenshot of the component.

From Command Line

You can also use the tool directly from the command line:

node src/cursor-integration.js http://localhost:3000 '{"waitTime": 1000}'

Options:

{
  // Wait time in milliseconds before taking screenshot
  "waitTime": 1000,

  // Perform an action before taking screenshot
  "action": {
    "element": { "id": "buttonId" }, // Can also use "class" or "selector"
    "action": "click" // click, hover, focus, type
  },

  // Take screenshot of specific element instead of full page
  "elementToCapture": { "id": "elementId" }
}

API

Taking Screenshots

import { takeScreenshot } from "./src/cursor-client.js";

// Take a full page screenshot
const result = await takeScreenshot("http://localhost:3000", {
  waitTime: 1000,
});

// Take a screenshot after clicking a button
const result = await takeScreenshot("http://localhost:3000", {
  action: {
    element: { id: "exampleButton" },
    action: "click",
  },
});

// Take a screenshot of a specific element
const result = await takeScreenshot("http://localhost:3000", {
  elementToCapture: { id: "content" },
});

Deleting Screenshots

import { deleteScreenshot } from "./src/cursor-client.js";

const deleteResult = await deleteScreenshot("/path/to/screenshot.png");

Integration with Cursor

This tool is designed to seamlessly integrate with Cursor:

1. Cursor generates code for a project
2. Cursor starts a local development server
3. Cursor invokes this tool with the local server URL
4. The tool visits the URL, performs actions, and takes screenshots
5. Cursor analyzes the screenshots to check if they match the prompt
6. Cursor can iteratively improve the code based on visual feedback

Examples

See the examples directory for usage examples.