Labsco
withLinda logo

Puppeteer Real Browser

★ 23

from withLinda

Enables powerful, detection-resistant browser automation for AI assistants using puppeteer-real-browser.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#payments#e-commerce#scraping#browser#documents#cloud

⚠️ UNDER MAINTENANCE - This project is still being actively developed. Some features may be incomplete or change without notice.

Puppeteer Real Browser MCP Server

Provides AI assistants with powerful, detection-resistant browser automation capabilities built on ZFC Digital's puppeteer-real-browser package.

License: MIT

Table of Contents

  1. Quick Start for Beginners
  2. Introduction
  3. Features
  4. Prerequisites
  5. Installation
  6. Usage
  7. Available Tools
  8. Advanced Features
  9. Configuration
  10. Troubleshooting
  11. Development
  12. Testing
  13. Contributing
  14. License

Introduction

The Puppeteer Real Browser MCP Server acts as a bridge between AI assistants and browser automation. It leverages puppeteer-real-browser to provide stealth browsing capabilities that can bypass common bot detection mechanisms.

This server implements the Model Context Protocol (MCP), allowing AI assistants to control a real browser, extract content, and more.

Features

  • Stealth by default: All browser instances use anti-detection features
  • Enhanced Windows support: Comprehensive Chrome detection and ECONNREFUSED error fixes (v1.3.0)
  • Smart Chrome detection: Registry-based detection + 15+ installation paths (Windows)
  • Connection resilience: Automatic localhost/127.0.0.1 fallback with port management
  • Multiple retry strategies: 5 different connection approaches with progressive fallback
  • Advanced configuration: Full support for all puppeteer-real-browser options
  • Dynamic selector discovery: Intelligent element finding without hardcoded selectors
  • Random scrolling: Tools for natural scrolling to avoid detection
  • Comprehensive toolset: 11 tools covering all browser automation needs
  • Proxy support: Built-in proxy configuration for enhanced privacy
  • Captcha handling: Support for solving reCAPTCHA, hCaptcha, and Turnstile
  • Robust error handling: Advanced error recovery with circuit breaker pattern
  • Stack overflow protection: Comprehensive protection against infinite recursion
  • Timeout controls: Automatic timeout mechanisms prevent hanging operations
  • Platform optimization: Windows-specific flags and longer timeouts for better compatibility

Available Tools

Core Browser Tools

Tool NameDescriptionRequired ParametersOptional Parameters
browser_initInitialize stealth browser with advanced optionsNoneheadless, disableXvfb, ignoreAllFlags, proxy, plugins, connectOption
navigateNavigate to a URLurlwaitUntil
get_contentGet page content (HTML or text)Nonetype, selector
browser_closeClose the browser instanceNoneNone

Interaction Tools

Tool NameDescriptionRequired ParametersOptional Parameters
clickStandard click on elementselectorwaitForNavigation
typeType text into input fieldselector, textdelay
waitWait for various conditionstype, valuetimeout
find_selectorFind CSS selector for element containing specific texttextelementType, exact

Behavior Tools

Tool NameDescriptionRequired ParametersOptional Parameters
random_scrollPerform random scrolling with natural timingNoneNone

Element Discovery Tools

Tool NameDescriptionRequired ParametersOptional Parameters
find_selectorFind CSS selector for element containing specific texttextelementType, exact

Content Tools

Tool NameDescriptionRequired ParametersOptional Parameters
save_content_as_markdownExtract page content and save it as a formatted markdown filefilePathcontentType, selector, formatOptions

Anti-Detection Tools

Tool NameDescriptionRequired ParametersOptional Parameters
solve_captchaAttempt to solve captchastypeNone

Advanced Features

Dynamic Selector Discovery

The server includes intelligent element discovery capabilities through the find_selector tool:

  • Text-based element finding: Automatically locates elements containing specific text
  • Smart CSS selector generation: Creates unique, robust CSS selectors similar to Chrome DevTools
  • Element type filtering: Optionally restrict search to specific HTML elements (e.g., buttons, links)
  • Exact or partial text matching: Choose between precise text matching or substring searches
  • Universal compatibility: Works across any website without hardcoded selectors

Example Usage:

Copy & paste — that's it
User: "Find the submit button that says 'Sign Up'"
AI: I'll locate that button for you.
[Uses find_selector with text: "Sign Up", elementType: "button"]

AI: Found button at selector: "form > button.btn-primary:nth-of-type(2)"

This approach eliminates the need for manually crafted selectors and makes automation more reliable across different websites.

Natural Interactions

The server includes tools designed for natural browsing behavior:

  • Random scrolling: Performs scrolling with natural timing and variable distances

This feature helps avoid detection by sophisticated bot-detection systems that analyze user behavior patterns.

Captcha Handling

The server includes basic support for solving common captcha types:

  • reCAPTCHA
  • hCaptcha
  • Cloudflare Turnstile

Note that captcha solving capabilities depend on the underlying puppeteer-real-browser implementation.

Development

Project Structure

Copy & paste — that's it
puppeteer-real-browser-mcp-server/
├── src/
│   ├── index.ts         # Main server implementation
│   └── stealth-actions.ts # Browser interaction functions
├── test/
│   └── test-server.ts   # Test script
├── package.json
└── tsconfig.json

Building from Source

Copy & paste — that's it
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Test the server
npm test

Adding New Tools

To add a new tool:

  1. Add the tool definition to the TOOLS array in src/index.ts
  2. Implement the tool handler in the CallToolRequestSchema handler
  3. Test the new tool functionality

Testing

This project includes a comprehensive testing suite with multiple categories optimized for different purposes:

Quick Tests (CI/CD) - ~30 seconds

Copy & paste — that's it
npm run test:quick    # Fast Jest tests for protocol compliance
npm test              # Alias for test:quick

Comprehensive Tests - ~5-10 minutes

Copy & paste — that's it
npm run test:full     # End-to-end MCP client testing

Performance Testing - ~2-3 minutes

Copy & paste — that's it
npm run test:performance  # Browser performance benchmarking

Performance tests measure:

  • Browser initialization timing (5 trials)
  • Navigation performance across different site types
  • Concurrent operation handling
  • Session longevity testing (30+ operations over 30 seconds)

Debug Tools - ~10 seconds

Copy & paste — that's it
npm run test:debug    # Environment diagnostics and troubleshooting

Debug tools provide:

  • Environment validation (Node.js version, platform, memory)
  • Chrome installation detection with specific paths
  • Quick server health check with startup timing
  • Network connectivity validation
  • Build status verification

All Tests - ~7-13 minutes

Copy & paste — that's it
npm run test:all      # Runs quick + full + performance tests
npm run test:dashboard # Unified test runner with reporting

The test dashboard provides:

  • Unified execution of multiple test categories
  • Real-time progress reporting
  • Performance metrics and timing
  • Overall test status summary
  • Recommendations for failed tests
  • JSON results saved to test-results/ directory

Integration Testing

Copy & paste — that's it
npm run test:integration  # Claude Code CLI integration testing

For detailed testing information, see TESTING.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

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

Acknowledgments

This MCP server is based on the excellent puppeteer-real-browser library by ZFC-Digital.

Thank you to the puppeteer-real-browser team for creating such a powerful and detection-resistant browser automation solution!