Google Search Tool

A Playwright-based Node.js tool that bypasses search engine anti-scraping mechanisms to execute Google searches and extract results. It can be used directly as a command-line tool or as a Model Context Protocol (MCP) server to provide real-time search capabilities to AI assistants like Claude.

中文文档

Key Features

• Local SERP API Alternative: No need to rely on paid search engine results API services, all searches are executed locally
• Advanced Anti-Bot Detection Bypass Techniques:
  • Intelligent browser fingerprint management that simulates real user behavior
  • Automatic saving and restoration of browser state to reduce verification frequency
  • Smart headless/headed mode switching, automatically switching to headed mode when verification is needed
  • Randomization of device and locale settings to reduce detection risk
• Raw HTML Retrieval: Ability to fetch the raw HTML of search result pages (with CSS and JavaScript removed) for analysis and debugging when Google's page structure changes
• Page Screenshot: Automatically captures and saves a full-page screenshot when saving HTML content
• MCP Server Integration: Provides real-time search capabilities to AI assistants like Claude without requiring additional API keys
• Completely Open Source and Free: All code is open source with no usage restrictions, freely customizable and extensible

Technical Features

• Developed with TypeScript, providing type safety and better development experience
• Browser automation based on Playwright, supporting multiple browser engines
• Command-line parameter support for search keywords
• MCP server support for AI assistant integration
• Returns search results with title, link, and snippet
• Option to retrieve raw HTML of search result pages for analysis
• JSON format output
• Support for both headless and headed modes (for debugging)
• Detailed logging output
• Robust error handling
• Browser state saving and restoration to effectively avoid anti-bot detection

Installation

# Install from source
git clone https://github.com/web-agent-master/google-search.git
cd google-search
# Install dependencies
npm install
# Or using yarn
yarn
# Or using pnpm
pnpm install

# Compile TypeScript code
npm run build
# Or using yarn
yarn build
# Or using pnpm
pnpm build

# Link package globally (required for MCP functionality)
npm link
# Or using yarn
yarn link
# Or using pnpm
pnpm link

Windows Environment Notes

This tool has been specially adapted for Windows environments:

1. .cmd files are provided to ensure command-line tools work properly in Windows Command Prompt and PowerShell
2. Log files are stored in the system temporary directory instead of the Unix/Linux /tmp directory
3. Windows-specific process signal handling has been added to ensure proper server shutdown
4. Cross-platform file path handling is used to support Windows path separators

Usage

Command Line Tool

# Direct command line usage
google-search "search keywords"

# Using command line options
google-search --limit 5 --timeout 60000 --no-headless "search keywords"

# Or using npx
npx google-search-cli "search keywords"

# Run in development mode
pnpm dev "search keywords"

# Run in debug mode (showing browser interface)
pnpm debug "search keywords"

# Get raw HTML of search result page
google-search "search keywords" --get-html