웹 검색 MCP 서버
Google 검색 기능과 고급 봇 감지 회피 기능을 갖춘 웹 콘텐츠 보기 기능을 제공하는 MCP 서버입니다.
특징
- 고급 필터링이 포함된 Google 맞춤 검색
- 마크다운 변환을 통한 웹 콘텐츠 보기
- 속도 제한 및 캐싱
- 브라우저 인스턴스 풀링
- Rebrowser-puppeteer를 이용한 봇 탐지 회피
필수 조건
- Bun 런타임 v1.0 이상
- Google API 자격 증명(API 키 및 검색 엔진 ID)
설치
지엑스피1
구성
쿠키 설정
인증된 사이트에 접속하려면 다음이 필요합니다.
- Get cookies.txt LOCALLY Chrome 확장 프로그램을 설치하세요
- 인증을 원하는 사이트를 방문하여 로그인하세요.
- 확장 프로그램을 사용하여 쿠키를 JSON 형식으로 내보내세요
- 내보낸 쿠키 파일을 안전한 위치에 저장하세요
BROWSER_COOKIES_PATH 환경 변수를 쿠키 파일의 절대 경로로 설정합니다.
MCP 서버 구성
MCP 설정 파일에 서버 구성을 추가합니다.
- Cline의 경우:
%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\cline_mcp_settings.json - Claude Desktop의 경우:
- MacOS/Linux:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"web-search": {
"command": "bun",
"args": [
"run",
"/ABSOLUTE/PATH/TO/web_search_mcp/dist/index.js"
],
"env": {
"GOOGLE_API_KEY": "your_api_key",
"GOOGLE_SEARCH_ENGINE_ID": "your_search_engine_id",
"MAX_CONCURRENT_BROWSERS": "3",
"BROWSER_TIMEOUT": "30000",
"RATE_LIMIT_WINDOW": "60000",
"RATE_LIMIT_MAX_REQUESTS": "60",
"SEARCH_CACHE_TTL": "3600",
"VIEW_URL_CACHE_TTL": "7200",
"MAX_CACHE_ITEMS": "1000",
"BROWSER_POOL_MIN": "1",
"BROWSER_POOL_MAX": "5",
"BROWSER_POOL_IDLE_TIMEOUT": "30000",
"REBROWSER_PATCHES_RUNTIME_FIX_MODE": "addBinding",
"REBROWSER_PATCHES_SOURCE_URL": "jquery.min.js",
"REBROWSER_PATCHES_UTILITY_WORLD_NAME": "util",
"REBROWSER_PATCHES_DEBUG": "0",
"BROWSER_COOKIES_PATH": "C:\\path\\to\\cookies.json",
"LOG_LEVEL": "info",
"NO_COLOR": "0",
"BUN_FORCE_COLOR": "1",
"FORCE_COLOR": "1"
}
}
}
}
/ABSOLUTE/PATH/TO/web_search_mcp 서버 디렉토리의 절대 경로로 바꾸세요.
로깅 구성
다음 환경 변수는 로깅 동작을 제어합니다.
LOG_LEVEL : 로깅 수준(error, warn, info, debug)을 설정합니다. 기본값: infoNO_COLOR : "1"로 설정하면 컬러 출력을 비활성화합니다.BUN_FORCE_COLOR : Bun 런타임에서 컬러 출력을 제어합니다(비활성화하려면 "0"으로 설정)FORCE_COLOR : 전역적으로 컬러 출력을 제어합니다(비활성화하려면 "0"으로 설정)
봇 감지 회피
이 서버는 봇 감지를 피하기 위해 rebrowser-puppeteer를 사용합니다.
- 런타임.누수 방지 활성화:
- Runtime.Enable 감지를 방지하기 위해 addBinding 기술을 사용합니다.
- 웹 워커 및 iframe과 함께 작동합니다.
- 주요 세계 컨텍스트에 대한 액세스를 유지합니다.
- 소스 URL 마스킹:
- Puppeteer의 sourceURL을 합법적인 스크립트처럼 보이도록 변경합니다.
- 자동화 도구 감지를 방지하는 데 도움이 됩니다.
- 유틸리티 세계 이름:
- 일반 유틸리티 세계 이름을 사용합니다.
- 세계 이름 패턴을 통한 감지 방지
- 브라우저 실행 구성:
- 자동화 플래그를 비활성화합니다
- 최적화된 Chrome 인수를 사용합니다.
- 뷰포트 및 창 설정을 구성합니다.
Claude Desktop과 함께 사용
- Claude Desktop이 설치되어 있고 최신 버전으로 업데이트되었는지 확인하세요.
- Claude Desktop 구성 파일을 엽니다.
- MacOS/Linux:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- 위의 구성 섹션에 표시된 대로 서버 구성을 추가합니다.
- Claude Desktop을 다시 시작하세요
- 망치 아이콘을 찾으세요
도구를 사용할 수 있는지 확인하려면
사용 가능한 도구
1. 검색 도구
{
name: "search",
params: {
query: string;
trustedDomains?: string[];
excludedDomains?: string[];
resultCount?: number;
safeSearch?: boolean;
dateRestrict?: string;
}
}
2. URL 보기 도구
{
name: "view_url",
params: {
url: string;
includeImages?: boolean;
includeVideos?: boolean;
preserveLinks?: boolean;
formatCode?: boolean;
}
}
문제 해결
Claude Desktop 통합 문제
- 로그를 확인하세요:
# MacOS/Linux
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\Logs\mcp*.log
- 일반적인 문제:
- 서버가 표시되지 않음: 구성 파일 구문 및 경로를 확인하세요.
- 도구 호출 실패: 서버 로그를 확인하고 Claude Desktop을 다시 시작하세요.
- 경로 문제: 절대 경로를 사용하고 있는지 확인하세요.
더 자세한 문제 해결 방법은 MCP 디버깅 가이드를 참조하세요.
개발
# Run in development mode with watch
bun --watch run dev
# Run tests
bun run test
# Run linter
bun run lint
중요 참고 사항
- 봇 감지:
- 봇 감지 회피 기능은 가장 일반적인 감지 방법을 방지하는 데 도움이 됩니다.
- 그러나 적절한 프록시 및 사용자 에이전트와 같은 추가 조치가 필요할 수 있습니다.
- 일부 웹사이트는 여전히 다른 수단을 통해 자동화를 감지할 수 있습니다.
- 성능:
- 브라우저 인스턴스는 풀링되어 재사용됩니다.
- 유휴 브라우저는 자동으로 정리됩니다.
- 리소스 제한으로 과부하 방지
특허
MIT