Browser MCP Server

봇 차단(anti-bot)에 대응하는 실제 브라우저를 AI 에이전트에 제공하는 MCP(Model Context Protocol) 서버입니다. Zyte API를 통해 페이지 이동, 클릭/입력/스크롤, 스크린샷 캡처, 구조화된 데이터 추출을 수행할 수 있으며, 프록시/IP 자동 순환과 차단 방지(ban avoidance)를 제공합니다.

NestJS와 @nestjs-mcp/server로 구축되었으며, Zyte의 /extract 엔드포인트와 HTTP로 직접 통신합니다. 전송은 streamable HTTP만 지원하며, 상태를 저장하지 않는(stateless) 방식으로 단일 /mcp 엔드포인트에서 제공됩니다.

설정

1. .env.example을 .env에 복사한 다음 내용을 입력합니다.

   변수	필수 여부	설명
   ZYTE_API_KEY	예	본인의 Zyte API 키
   ZYTE_API_BASE_URL	아니오	Zyte API 기본 URL을 재정의합니다 (기본값 https://api.zyte.com/v1)
   PORT	아니오	HTTP 포트 (기본값 3000)
   BROWSER_TIMEOUT_MS	아니오	Zyte 호출 건별 타임아웃 (기본값 30000)
   BROWSER_MAX_RETRIES	아니오	rate-limit(429/503) 및 임시 차단(520) 응답에 대한 재시도 횟수이며, 지수 백오프를 적용합니다 (기본값 2)

2. 의존성을 설치하고 서버를 시작합니다.

   pnpm install
   pnpm run start:dev

   MCP 엔드포인트는 http://localhost:3000/mcp에서 제공됩니다.

Related MCP server: Stealth Browser MCP

도구

browser_browse, browser_screenshot, browser_extract는 선택적으로 sessionId(이전 호출에서 반환된 값)를 받아 여러 도구 호출에 걸쳐 동일한 IP 주소와 cookie jar를 재사용할 수 있습니다. 로그인 상태를 유지하거나 다단계 작업에서 IP를 일관되게 유지하는 데 유용합니다. 단, Zyte의 세션 문서에 따르면 이 기능은 호출 사이에 실제 브라우저/탭 상태(페이지 내 폼 입력, 스크롤 위치, 열려 있는 모달 등)를 유지하지 않습니다. 각 호출은 동일한 네트워크 식별자와 쿠키로 새 페이지를 로드합니다.

actions는 결과를 캡처하기 전에 실행되는 일련의 단계로, click, type, select, hover, keyPress, scrollBottom, scrollTo, waitForSelector, waitForTimeout, waitForNavigation, goto, evaluate를 지원합니다. 요소를 대상으로 하는 액션은 selector: { type: "css" | "xpath", value: string } 형태의 선택자를 받습니다.

browser_search는 Zyte의 별도 /v1/search 엔드포인트(/v1/extract 아님)에 요청을 보내며, domain(지원되는 검색 엔진, 예: "google.com"), query, 그리고 선택적으로 maxResults(10-100)/geolocation/locale를 받습니다.

rate-limit(429/503) 및 임시 차단(520)에 해당하는 Zyte 응답은 Zyte의 오류 처리 가이드에 따라 지수 백오프(exponential backoff)로 BROWSER_MAX_RETRIES회까지 자동으로 재시도됩니다. 그 외의 오류 응답(잘못된 요청, 영구 차단, 계정 정지)은 즉시 표시되며, 가능한 경우 Zyte 오류의 type이 메시지에 포함됩니다.

클라이언트 연결하기

실행 중인 인스턴스를 가리키는 원격 MCP 클라이언트 구성 예시(예: Claude Desktop / Claude Code):

{
  "mcpServers": {
    "browser": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

테스트

pnpm test        # unit tests (service + resolver, global fetch mocked)
pnpm run lint    # eslint
pnpm run build   # type-check + compile

단위 테스트는 Zyte를 호출하는 데 사용되는 전역 fetch를 모킹합니다. 라이브 API에 대한 엔드투엔드 검증을 위해 실제 ZYTE_API_KEY로 서버를 실행하고, pnpm dlx @modelcontextprotocol/inspector http://localhost:3000/mcp 또는 curl을 사용하여 initialize → tools/list → tools/call을 실행하세요.