google-surf-mcp

✨안티 봇 검색 MCP: API 키 불필요✨

English | 한국어

데모 전용입니다. 실제 검색은 기본적으로 헤드리스(headless)(브라우저가 보이지 않음)로 실행됩니다. 위 영상처럼 Chrome을 보이게 하려면 SURF_HEADLESS=false로 설정하세요.

Google 검색 MCP입니다. API 키가 필요 없습니다. 그냥 작동합니다.

• ✅ 실제로 작동함 (6개의 무료 Google 검색 MCP를 테스트했으나 모두 실패함)

• ✅ 검색 + URL 추출을 하나의 MCP에서 수행 (일반적인 검색 MCP + 가져오기 MCP 조합을 대체)

• ✅ 4가지 도구: search / search_parallel / extract / search_extract

• ✅ API 키, 프록시, 솔버 불필요

• ✅ 자동 CAPTCHA 복구 (Chrome이 열리면 사람이 한 번 해결하고, 호출이 재시도됨)

• ✅ extract에 대한 SSRF 방어 (기본적으로 localhost, 사설 IP, AWS 메타데이터 차단)

정보

모든 MCP 클라이언트에 연결하면 Google 검색을 도구로 사용할 수 있습니다.

CAPTCHA 솔버가 없습니다. 도구 사용 중 CAPTCHA가 발생하면 사람이 해결할 수 있도록 Chrome 창이 열립니다. 해결할 때마다 Google에 대한 프로필 평판이 유지됩니다. 지속 가능하고 윤리적인 사용을 위해 설계되었습니다.

최초 1회 설치 시 약 1초간의 프로필 예열이 필요합니다(설치 섹션 참조).

로컬 사용을 위해 설계되었습니다. 상태 비저장(stateless) 또는 서버리스 배포에는 적합하지 않습니다.

Related MCP server: G-Search MCP

성능 수치

1Gb/s 연결 환경의 워크스테이션에서 측정되었습니다.

스택

• Playwright + 영구 Chrome 프로필

• playwright-extra 스텔스

• 속도를 위해 이미지 / 미디어 / 폰트 리소스 차단

• 첫 실행 전 원샷 프로필 부트스트랩

• 기사 추출을 위한 Mozilla Readability + Turndown

설치

Node 18+ 및 시스템에 Google Chrome(또는 Chromium)이 필요합니다.

npx google-surf-mcp   # actual MCP - register in client config

또는 로컬 클론:

git clone https://github.com/HarimxChoi/google-surf-mcp
cd google-surf-mcp
npm install
npm run bootstrap

bootstrap은 Chrome 창을 엽니다. 그 안에서 Google 검색을 한 번 수행하세요. 닫으세요. 이제 프로필이 예열되었습니다.

필요한 경우 경로를 재정의하세요:

CHROME_PATH=/path/to/chrome SURF_TZ=America/New_York npm run bootstrap

Claude Code와 함께 사용

~/.claude.json에 다음을 붙여넣으세요:

{
  "mcpServers": {
    "google-surf": {
      "command": "npx",
      "args": ["-y", "google-surf-mcp"]
    }
  }
}

Claude Code를 재시작하세요. 완료되었습니다. 이제 search, search_parallel, extract, search_extract를 사용할 수 있습니다.

다른 MCP 클라이언트의 경우, 해당 설정 파일에 동일한 JSON 형식을 사용하세요.

로컬 클론 변형:

{
  "mcpServers": {
    "google-surf": {
      "command": "node",
      "args": ["/abs/path/to/google-surf-mcp/build/index.js"]
    }
  }
}

도구

• search(query, limit?) - 단일 쿼리, ~1.5초. 제목 / URL / 스니펫을 반환합니다. 스폰서 광고는 필터링됩니다.

• search_parallel(queries[], limit?) - 4개 풀, 호출당 최대 10개 쿼리.

• extract(url, max_chars?) - URL을 가져와 기사 마크다운을 반환합니다(텍스트 폴백이 포함된 Readability). 실패 시 { error }를 반환하며, 절대 에러를 던지지 않습니다.

• search_extract(query, limit?, max_chars?) - 검색 + 병렬 추출을 한 번에 수행합니다. 전체 기사 내용이 포함된 SERP 결과를 반환합니다. 페이지별 실패는 격리됩니다.

search_extract가 핵심 도구입니다: 단일 호출로 SERP + 전체 기사 내용을 가져옵니다. 대부분의 에이전트가 조합해서 사용하는 "검색 MCP + URL 가져오기 MCP" 조합을 대체합니다.

환경 변수

문제 해결

• CAPTCHA: 보이는 Chrome 창이 자동으로 열립니다(4가지 도구 모두 작동). 한 번 해결하고 그 안에서 검색을 한 번 수행하면, 호출이 재시도되고 계속 진행됩니다. 대신 빠르게 실패하게 하려면 디스플레이가 연결되지 않은 상태에서 실행하세요.

• "Chrome not found": Chrome을 설치하거나 CHROME_PATH를 설정하세요.

• 오래된 선택자(selectors): Google은 클래스명을 자주 변경합니다. PR을 환영합니다.

변경 로그

CHANGELOG.md를 참조하세요.

라이선스

MIT