Merajmehrabi Puppeteer MCP Server

🚀 Puppeteer MCP Server

This MCP server provides browser automation capabilities through Puppeteer, supporting interactions with new browser instances and existing Chrome windows.

✨ Features

• Browse web pages
• Take screenshots
• Click elements
• Fill out forms
• Select options
• Hover over elements
• Execute JavaScript
• Intelligent Chrome tab management:
  • Connect to active Chrome tabs
  • Preserve existing Chrome instances
  • Handle connections intelligently

📦 Project Structure

/
├── src/
│   ├── config/        # Configuration module
│   ├── tools/         # Tool definitions and handlers
│   ├── browser/       # Browser connection management
│   ├── types/         # TypeScript type definitions
│   ├── resources/     # Resource handlers
│   └── server.ts      # Server initialization
├── index.ts           # Entry point
└── README.md         # Documentation

💻 Usage Examples

Basic Usage

The server starts a new browser instance by default.

Advanced Usage

To connect to an existing Chrome window:

1. Completely close any existing Chrome instances.
2. Start Chrome with remote debugging enabled:
   • Windows or Linux: chrome.exe --remote-debugging-port=9222
   • Mac: open -a /Applications/Google\ Chrome.app --args --remote-debugging-port=9222
3. Open a new tab containing devtoolsFrontendUrl.

📚 Tool List

• puppeteer_connect_active_tab: Connect to an active Chrome tab
• puppeteer_create_new_tab: Create a new Chrome tab
• puppeteer_navigate_to_url: Navigate to a specified URL
• puppeteer_close_current_tab: Close the current tab
• puppeteer_screenshot_page: Take a screenshot of the page

⚠️ Important Note

• Run the server only in a trusted environment.
• Do not transmit sensitive information in plain text in a production environment.
• Regularly update dependencies to prevent security vulnerabilities.

📄 Logging

Overview

The server provides detailed logging functionality, including:

• Operation timestamps
• Request context information
• Operation execution results
• Error details

All logs are stored in the ./logs/ directory by default, separated by date.

🔧 Error Handling

Supported Error Types

• Connection failure
• Missing elements
• Invalid selectors
• JavaScript execution errors
• Screenshot capture failure

Each tool call returns:

• Success/failure status
• Detailed error information in case of failure
• Result data of successful operations

All errors are logged in the log file, including:

• Timestamp
• Error message
• Stack trace (if available)
• Context information

🤝 Contribution Guidelines

Contributions are welcome! Please refer to our CONTRIBUTING.md to learn how to submit pull requests, report issues, and contribute to the project.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.