Playwright 기반의 Node.js 도구로, 검색 엔진의 안티 스크래핑 메커니즘을 우회하여 구글 검색을 실행하고 결과를 추출합니다. 명령줄 도구로 직접 사용하거나 Model Context Protocol(MCP) 서버로 사용되어 Claude와 같은 AI 비서에게 실시간 검색 기능을 제공합니다.

中文文档

주요 특징

• 로컬 SERP API 대안: 유료 검색 결과 API 서비스에 의존할 필요 없으며, 모든 검색이 로컬에서 실행됩니다
• 고급 안티-봇 탐지 우회 기술:
• 실제 사용자 행동을 시뮬레이션하는 지능형 브라우저 지문 관리
• 검증 빈도를 줄이기 위한 브라우저 상태 자동 저장 및 복원
• 스마트 헤드리스/헤드 모드 전환, 검증이 필요할 때 자동으로 헤드 모드로 전환
• 탐지 위험을 줄이기 위한 장치 및 지역 설정의 무작위화
• 원본 HTML 검색: 구글 페이지 구조가 변경될 때 분석 및 디버거링을 위해 검색 결과 페이지의 원본 HTML(CSS와 자바스크립트 제거) 기능을 제공합니다
• 페이지 스크린샷: HTML 콘텐츠를 저장할 때 전체 페이지 스크린샷을 자동으로 캡처하여 저장합니다

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