web-agent-master/google-search

Playwright 기반의 Node.js 도구로, 검색 엔진의 안티 스크래핑 (anti-scraping) 메커니즘을 우회하여 Google 검색을 실행하고 결과를 추출합니다. 이 도구는 명령줄 도구 (command-line tool)로 직접 사용하거나, Claude와 같은 AI 어시스턴트에게 실시간 검색 기능을 제공하는 Model Context Protocol (MCP) 서버로 사용할 수 있습니다.

로컬 SERP API 대안: 유료 검색 엔진 결과 API 서비스에 의존할 필요 없이, 모든 검색이 로컬에서 실행됩니다.

고급 안티 봇 (Anti-Bot) 탐지 우회 기술:

• 실제 사용자 행동을 시뮬레이션하는 지능형 브라우저 핑거프린트 (browser fingerprint) 관리
• 인증 빈도를 줄이기 위한 브라우저 상태의 자동 저장 및 복구
• 스마트 헤드리스/헤디드 (headless/headed) 모드 전환, 인증이 필요할 때 자동으로 헤디드 모드로 전환
• 탐지 위험을 줄이기 위한 장치 및 로캘 (locale) 설정의 무작위화

Raw HTML 검색: Google의 페이지 구조가 변경될 때 분석 및 디버깅을 위해 검색 결과 페이지의 Raw HTML (CSS 및 JavaScript 제거됨)을 가져오는 기능

페이지 스크린샷: HTML 콘텐츠를 저장할 때 전체 페이지 스크린샷을 자동으로 캡처하고 저장

MCP 서버 통합: 추가적인 API 키 없이도 Claude와 같은 AI 어시스턴트에게 실시간 검색 기능 제공

완전한 오픈 소스 및 무료: 모든 코드는 오픈 소스이며 사용 제한이 없고, 자유롭게 커스터마이징 및 확장이 가능합니다.

• TypeScript로 개발되어 타입 안정성 (type safety)과 더 나은 개발 경험 제공
• Playwright 기반의 브라우저 자동화로 다양한 브라우저 엔진 지원
• 검색 키워드를 위한 명령줄 파라미터 지원
• AI 어시스턴트 통합을 위한 MCP 서버 지원
• 제목, 링크, 스니펫 (snippet)을 포함한 검색 결과 반환
• 분석을 위한 검색 결과 페이지의 Raw HTML 가져오기 옵션
• JSON 형식 출력
• 헤드리스 및 헤디드 모드 모두 지원 (디버깅용)
• 상세한 로깅 (logging) 출력
• 강력한 에러 핸들링 (error handling)
• 안티 봇 탐지를 효과적으로 피하기 위한 브라우저 상태 저장 및 복구

# 소스에서 설치
git clone https://github.com/web-agent-master/google-search.git
cd google-search
...

이 도구는 Windows 환경에 맞춰 특별히 조정되었습니다:

• Windows 명령 프롬프트(Command Prompt) 및 PowerShell에서 명령줄 도구(command-line tools)가 제대로 작동하도록 .cmd 파일이 제공됩니다.
• 로그 파일이 Unix/Linux의 /tmp 디렉토리 대신 시스템 임시 디렉토리에 저장됩니다.
• 적절한 서버 종료를 보장하기 위해 Windows 전용 프로세스 시그널 핸들링 (process signal handling)이 추가되었습니다.
• Windows 경로 구분자 (path separators)를 지원하기 위해 크로스 플랫폼 파일 경로 핸들링 (Cross-platform file path handling)이 사용되었습니다.

# 직접적인 명령줄 사용
google-search "search keywords"
# 명령줄 옵션 사용
...

-l, --limit <number>: 결과 개수 제한 (기본값: 10)
-t, --timeout <number>: 밀리초 단위 타임아웃 (default: 60000)
--no-headless: 브라우저 인터페이스 표시 (디버깅용)
--remote-debugging-port <number>: 원격 디버깅 포트 활성화 (기본값: 9222)
--state-file <path>: 브라우저 상태 파일 경로 (기본값: ./browser-state.json)
--no-save-state: 브라우저 상태를 저장하지 않음
--get-html: 결과를 파싱하는 대신 검색 결과 페이지의 원본 HTML을 가져옴
--save-html: HTML을 파일로 저장 (--get-html과 함께 사용)
--html-output <path>: HTML 출력 파일 경로 지정 (--get-html 및 --save-html과 함께 사용)
-V, --version: 버전 번호 표시
-h, --help: 도움말 정보 표시

{
"query": "deepseek",
"results": [
...

--get-html 옵션을 사용할 때, 출력에는 HTML 콘텐츠에 대한 정보가 포함됩니다:

{
"query": "playwright automation",
"url": "https://www.google.com/",
...

--save-html 옵션도 함께 사용하는 경우, 출력에는 HTML이 저장된 경로가 포함됩니다:

{
"query": "playwright automation",
"url": "https://www.google.com/",
...

이 프로젝트는 Model Context Protocol (MCP) 서버 기능을 제공하여, Claude와 같은 AI 어시스턴트가 Google 검색 기능을 직접 사용할 수 있도록 합니다. MCP는 AI 어시스턴트가 외부 도구 및 데이터에 안전하게 접근할 수 있도록 지원하는 개방형 프로토콜 (Open Protocol)입니다.

# 프로젝트 빌드
pnpm build

Claude Desktop 설정 파일을 수정하세요:

• Mac:
  ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows:
  %APPDATA%\Claude\claude_desktop_config.json

• 일반적으로 다음 위치에 있습니다:
  C:\Users\username\AppData\Roaming\Claude\claude_desktop_config.json

• Windows 탐색기 주소창에
  %APPDATA%\Claude를
  입력하여 직접 접근할 수 있습니다.

• 일반적으로 다음 위치에 있습니다:

• Mac:

서버 설정을 추가하고 Claude를 재시작하세요.

{
"mcpServers": {
"google-search": {
...

Windows 환경의 경우, 다음 설정들을 사용할 수도 있습니다:

• npx와 함께 cmd.exe 사용:

{
"mcpServers": {
"google-search": {
...

• node와 전체 경로 사용 (위 방법에서 문제가 발생할 경우 권장됨):

{
"mcpServers": {
"google-search": {
...

참고: 두 번째 방법의 경우, C:/path/to/your/google-search를 google-search 패키지가 설치된 실제 전체 경로로 반드시 교체해야 합니다.

통합 후에는 Claude에서 "최신 AI 연구 검색해줘"와 같이 검색 기능을 직접 사용할 수 있습니다.

google-search/
├── package.json # 프로젝트 설정 및 의존성 (Dependencies)
├── tsconfig.json # TypeScript 설정
...

TypeScript: 개발 언어로, 타입 안정성 (Type safety) 및 더 나은 개발 경험을 제공합니다.
Node.js: JavaScript/TypeScript 코드를 실행하기 위한 런타임 환경 (Runtime environment)입니다.
Playwright: 브라우저 자동화 (Browser automation)를 위한 도구로, 여러 브라우저를 지원합니다.
Commander: 명령줄 인자 (Command line arguments) 파싱 및 도움말 정보 생성을 위한 도구입니다.
Model Context Protocol (MCP): AI 어시스턴트 통합을 위한 개방형 프로토콜 (Open protocol)입니다.
MCP SDK: MCP 서버 구현을 위한 개발 툴킷 (Development toolkit)입니다.
Zod: 검증 (Validation) 및 타입 안정성을 위한 스키마 정의 라이브러리 (Schema definition library)입니다.
pnpm: 디스크 공간과 설치 시간을 절약하는 효율적인 패키지 관리 도구 (Package management tool)입니다.

모든 명령은 프로젝트 루트 디렉토리에서 실행할 수 있습니다:

# 의존성 설치 (Install dependencies)
pnpm install
# Playwright 브라우저 설치
...

# 개발 모드에서 실행 (Run in development mode)
pnpm dev "search keywords"
# 디버그 모드에서 실행 (브라우저 인터페이스 표시)
...

# 개발 모드에서 MCP 서버 실행 (Run MCP server in development mode)
pnpm mcp
# 컴파일된 MCP 서버 실행
...

이 도구는 강력한 오류 처리 (Error handling) 메커니즘을 내장하고 있습니다:

• 브라우저 시작 실패 시 친절한 오류 메시지 제공

• 네트워크 연결 문제 발생 시 자동 오류 상태 반환

• 검색 결과 파싱 실패 시 상세 로그 제공

• 타임아웃 (Timeout) 상황 발생 시 원활한 종료 및 유용한 정보 반환

• 이 도구는 학습 및 연구 목적으로만 사용하십시오.

• Google의 서비스 약관 및 정책을 준수하십시오.

• Google에 의해 차단되는 것을 방지하기 위해 요청을 너무 빈번하게 보내지 마십시오.

• 일부 지역에서는 Google 접속을 위해 프록시 (Proxy)가 필요할 수 있습니다.

• Playwright는 브라우저를 설치해야 하며, 이는 첫 사용 시 자동으로 다운로드됩니다.

• 상태 파일 (State files)에는 브라우저 쿠키 및 저장 데이터가 포함되어 있으므로 안전하게 보관하십시오.

• 상태 파일을 사용하면 Google의 안티 봇 (Anti-bot) 탐지를 효과적으로 피하고 검색 성공률을 높일 수 있습니다.

• MCP 서버는 Node.js v16 이상이 필요합니다.

• MCP 서버를 사용할 때는 Claude Desktop이 최신 버전인지 확인하십시오.

• Claude Desktop을 설정할 때는 MCP 서버 파일에 대한 절대 경로 (Absolute paths)를 사용하십시오.

• Windows 환경에서는 Playwright 브라우저를 처음 설치할 때 관리자 권한 (Administrator privileges)이 필요할 수 있습니다.

• 권한 문제 (Permission issues)가 발생하면 명령 프롬프트 (Command Prompt) 또는 PowerShell을 관리자 권한으로 실행해 보십시오.

• Windows 방화벽 (Windows Firewall)이 Playwright 브라우저의 네트워크 연결을 차단할 수 있습니다. 메시지가 표시되면 액세스를 허용하십시오.

• 브라우저 상태 파일 (Browser state files)은 기본적으로 사용자의 홈 디렉토리에 .google-search-browser-state.json으로 저장됩니다.

• 로그 파일 (Log files)은 시스템 임시 디렉토리 내의 google-search-logs 폴더에 저장됩니다.

유료 검색 엔진 결과 API 서비스 (SerpAPI 등)와 비교했을 때, 이 프로젝트는 다음과 같은 장점을 제공합니다:

완전 무료 (Completely Free): API 호출 비용이 발생하지 않습니다.
로컬 실행 (Local Execution): 모든 검색이 로컬에서 실행되며, 제3자 서비스에 의존하지 않습니다.
개인정보 보호 (Privacy Protection): 검색 쿼리가 제3자에 의해 기록되지 않습니다.
커스터마이징 가능 (Customizability): 완전한 오픈 소스 (Open source)로, 필요에 따라 수정 및 확장이 가능합니다.
사용 제한 없음 (No Usage Limits): API 호출 횟수나 빈도 제한을 받지 않습니다.
MCP 통합 (MCP Integration): Claude와 같은 AI 어시스턴트와의 통합을 기본적으로 지원합니다.