Puppeteer MCP server

This MCP server provides browser automation capabilities through Puppeteer, allowing you to interact with both new browser instances and existing Chrome windows. It enables web navigation, taking screenshots, interacting with page elements, and executing JavaScript through the Model Context Protocol.

Installation

From npm

You can install the server globally:

npm install -g puppeteer-mcp-server

Or run it directly without installation:

npx puppeteer-mcp-server

From source

1. Clone the repository or download the source code
2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run the server:

npm start

Configuration

To use this server with Claude, add it to your MCP settings configuration file.

For Claude Desktop App

Add to your Claude Desktop configuration file:

If installed globally via npm:

{
  "mcpServers": {
    "puppeteer": {
      "command": "puppeteer-mcp-server",
      "args": [],
      "env": {}
    }
  }
}

Using npx (without installation):

{
  "mcpServers": {
    "puppeteer": {
      "command": "npx",
      "args": ["-y", "puppeteer-mcp-server"],
      "env": {}
    }
  }
}

If installed from source:

{
  "mcpServers": {
    "puppeteer": {
      "command": "node",
      "args": ["path/to/puppeteer-mcp-server/dist/index.js"],
      "env": {
        "NODE_OPTIONS": "--experimental-modules"
      }
    }
  }
}

For Claude VSCode Extension

Add similar configuration to your Claude VSCode extension MCP settings file, adjusting the command path as needed.

Usage Modes

Standard Mode

By default, the server launches a new browser instance for each session.

Active Tab Mode

To connect to an existing Chrome window:

1. Close any existing Chrome instances completely

2. Launch Chrome with remote debugging enabled:

   # Windows
   "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
   
   # macOS
   /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
   
   # Linux
   google-chrome --remote-debugging-port=9222
   

3. Navigate to your desired webpage in Chrome

4. Connect using the puppeteer_connect_active_tab tool:

   {
     "targetUrl": "https://example.com", 
     "debugPort": 9222
   }
   

Available Tools

puppeteer_connect_active_tab

Connect to an existing Chrome instance with remote debugging enabled.

• Optional parameters:
  • targetUrl - URL of the specific tab to connect to
  • debugPort - Chrome debugging port (default: 9222)

puppeteer_navigate

Navigate to a URL.

• Required: url - The URL to navigate to

puppeteer_screenshot

Take a screenshot of the current page or a specific element.

• Required: name - Name for the screenshot
• Optional:
  • selector - CSS selector for element to screenshot
  • width - Width in pixels (default: 800)
  • height - Height in pixels (default: 600)

puppeteer_click

Click an element on the page.

• Required: selector - CSS selector for element to click

puppeteer_fill

Fill out an input field.

• Required:
  • selector - CSS selector for input field
  • value - Text to enter

puppeteer_select

Use dropdown menus.

• Required:
  • selector - CSS selector for select element
  • value - Option value to select

puppeteer_hover

Hover over elements.

• Required: selector - CSS selector for element to hover

puppeteer_evaluate

Execute JavaScript in the browser console.

• Required: script - JavaScript code to execute

Security Considerations

When using remote debugging:

• Only enable on trusted networks
• Use a unique debugging port
• Close debugging port when not in use
• Never expose debugging port to public networks

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.