Puppeteer MCP Server

🚀 Puppeteer MCP Server Documentation

Puppeteer is a library developed by Google for controlling the Chrome browser via the WebDriver protocol. It offers a rich set of APIs for browser operations, including navigation, screenshot capture, and element manipulation.

🚀 Quick Start

✨ Features

Puppeteer provides a wide range of features for browser automation, such as:

• Navigating to web pages
• Taking screenshots
• Manipulating DOM elements
• Interacting with forms

📦 Installation

Standard Installation

Run the following commands to clone the repository and install dependencies:

git clone https://github.com/your-repository.git
cd puppeteer-mcp-server
npm install

Development Environment Configuration

1. Ensure Node.js (version 14 or higher) and npm are installed.
2. Install project dependencies:

   npm install
   

3. Start the development server:

   npm run dev
   

Production Environment Deployment

1. Install project dependencies:

   npm install --production
   

2. Start the production server:

   npm start
   

💻 Usage Examples

Basic Usage

By default, the server will launch a new browser instance.

Advanced Usage

To connect to an existing Chrome window:

1. Completely close all existing Chrome instances.
2. Enable remote debugging when starting Chrome:

   # 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 the desired web page in Chrome.
4. Use the puppeteer_connect_active_tab tool to connect:

   {
     "targetUrl": "https://example.com", // Optional: Specify the URL of the tab to connect to
     "debugPort": 9222 // Optional: Default is 9222
   }
   

The server will:

• Detect and connect to a running Chrome instance with remote debugging enabled.
• Keep your Chrome instance open (it won't close it).
• Find and connect to non-extension tabs.
• Provide clear error messages in case of connection failure.

📚 Documentation

Available Tools

• puppeteer_connect_active_tab: Connect to an existing Chrome instance with remote debugging enabled.
  • Optional parameters:
    • targetUrl: The URL of the specific tab to connect to.
    • debugPort: The Chrome debugging port (default is 9222).
• puppeteer_navigate: Navigate to a specified URL.
  • Required parameter:
    • url: The URL to navigate to.
• puppeteer_screenshot: Take a screenshot of the current page or a specific element.
  • Required parameter:
    • name: The name of the screenshot.
  • Optional parameters:
    • selector: The CSS selector for the element to take a screenshot of.
    • width: The width in pixels (default is 800).
    • height: The height in pixels (default is 600).
• puppeteer_click: Click on an element on the page.
  • Required parameter:
    • selector: The CSS selector of the element to click.
• puppeteer_fill: Fill in the content of an input field.
  • Required parameters:
    • selector: The CSS selector of the input field.
    • value: The value to fill in.
• puppeteer_submit_form: Submit a form.
  • Required parameter:
    • selector: The CSS selector of the form element or its parent container.

Security Considerations

• In a production environment, ensure the server runs on a secure network and configure appropriate security policies.
• Avoid storing sensitive information in plain text in the code. It is recommended to use environment variables.
• Regularly update dependencies to prevent known security vulnerabilities.

Logging

• Log Levels:
  • debug: Debug mode, outputs detailed log information.
  • info: Default mode, outputs general information logs.
  • warn: Warning mode, outputs logs for potential issues.
  • error: Error mode, outputs logs for serious errors.
• Log Format:

  {
    "timestamp": "2023-10-26T15:36:40.123Z",
    "level": "info",
    "message": "Server started on port 8080"
  }
  

Error Handling

• Common Errors:
  • Cannot connect to browser instance:

    Error: Cannot connect to browser instance
    

    Solution:
    • Ensure the Chrome browser is running.
    • Check if the remote debugging port is correctly configured.
  • Page not loaded:

    Error: Page not loaded
    

    Solution:
    • Ensure the target URL is available.
    • Increase the waiting time or use appropriate page load event listeners.

Advanced Features

• Custom Browser Configuration: Customize browser options at startup:

  {
    "executablePath": "/path/to/chrome",
    "args": ["--incognito"],
    "userDataDir": "/path/to/user/data"
  }
  

• Extension Support: Enhance browser functionality by loading extensions:

  "extensions": ["/path/to/extension.crx"]
  

🔧 Technical Details

Development Guide

• Contributing Code:
  1. Create a branch for your changes.
  2. Commit and push your changes.
  3. Create a pull request for review.
• Reporting Issues:
  1. Open the Issues page.
  2. Describe the problem in detail and provide steps to reproduce it.

📄 License

This project is licensed under the MIT License. For details, please refer to the LICENSE file.

Contributors

Thank you to the following contributors for their support of the project:

• Zhang San
• Li Si
• Wang Wu

Appendix

• Command Line Options:

  # Start the server
  npm start -- --port 8081
  
  # Run tests
  npm test
  
  # Package the project
  npm run build
  

• FAQ:
  • Q: How to handle CORS issues? A: Enable cross-origin resource sharing in the configuration:

    "cors": {
      "enabled": true,
      "origin": "*"
    }
    

  • Q: How to capture browser screenshots? A: Use the page.screenshot() method and specify the output path and format.
• Contact Information: For more information, please visit the project homepage or contact the maintainers.