Hyperbrowser MCP로 웹 자동화하기

핵심 요약

Hyperbrowser MCP는 AI가 웹 페이지를 스크래핑·추출·크롤링할 수 있게 해주는 표준화된 서버입니다. Node.js 환경에서 간단한 설치와 JSON 기반 설정만으로 기존 MCP 클라이언트(예: Claude)에 바로 붙여 사용할 수 있습니다.

Hyperbrowser MCP 개념 한 번에 이해하기

Hyperbrowser MCP는 "AI용 헤드리스 브라우저 API 서버" 정도로 보면 됩니다.

AI 모델이 직접 브라우저를 띄우지 않고, MCP 프로토콜을 통해 이 서버에 요청을 보내면 웹 페이지 내용 가져오기, 구조화된 데이터 추출, 여러 페이지 크롤링까지 모두 처리해 반환해 줍니다.

업무 자동화 관점에서 보면, 기존에 Puppeteer/Playwright를 직접 짜서 하던 작업의 상당 부분을 "도메인 특화된 원격 브라우저 서비스"로 추상화한 것에 가깝습니다.

설치와 기본 실행 흐름

Hyperbrowser MCP 서버는 Node.js 기반으로 동작합니다.

로컬에 Node.js만 있으면 다음 한 줄로 설치와 실행을 동시에 처리할 수 있습니다.

npx hyperbrowser-mcp

이 명령은 MCP 서버를 띄우는 역할을 하고, 실제 사용은 MCP 클라이언트(예: Claude, 기타 MCP 호환 IDE/툴)에서 이 서버를 등록하는 방식으로 진행됩니다.

즉, 구조는 "MCP 클라이언트 ⇄ Hyperbrowser MCP 서버 ⇄ 실제 웹 사이트" 형태로 이해하면 됩니다.

MCP 클라이언트에서의 설정 방식

MCP 클라이언트는 보통 JSON 설정으로 외부 MCP 서버를 등록합니다.

Hyperbrowser MCP를 붙일 때는 다음과 같이 command와 args를 지정하고, 환경 변수로 API 키를 넘겨줍니다.

{
  "mcpServers": {
    "hyperbrowser": {
      "command": "npx",
      "args": ["hyperbrowser-mcp"],
      "env": {
        "HYPERBROWSER_API_KEY": "your-api-key"
      }
    }
  }
}

이 구조의 포인트는 세 가지입니다. 첫째, MCP 서버 이름(hyperbrowser)은 클라이언트에서 이 서버를 호출할 때의 식별자 역할을 합니다. 둘째, command/args 조합으로 실제 실행 커맨드를 정의합니다. 셋째, env를 통해 민감한 설정(API 키)을 코드와 분리해 전달합니다.

MCP를 여러 개 붙이는 환경이라면, 이 패턴을 재사용해 각기 다른 웹/도메인용 MCP 서버를 병렬로 구성할 수 있습니다.

환경 변수 전달이 안 되는 클라이언트 대응 전략

일부 MCP 클라이언트(예: 특정 IDE)는 설정 JSON에서 env를 지원하지 않습니다.

이 경우에는 셸 스크립트를 하나 감싸서 사용하는 방식으로 해결합니다.

{
  "mcpServers": {
    "hyperbrowser": {
      "command": "bash",
      "args": ["/path/to/hyperbrowser-mcp/run_server.sh"]
    }
  }
}

그리고 run_server.sh에 다음처럼 API 키를 포함합니다.

#!/bin/bash
export HYPERBROWSER_API_KEY="your-api-key"
npx hyperbrowser-mcp

결국 "클라이언트 → bash → 스크립트 → Hyperbrowser MCP"의 체인을 만들고, 환경 변수 세팅 책임을 스크립트로 옮기는 패턴입니다.

실무에선 이 스크립트를 .env 로딩, 로깅, 프록시 설정 등과 함께 확장해 하나의 진입점으로 만드는 것이 깔끔합니다.

웹 페이지 스크래핑: scrape_webpage

scrape_webpage는 단일 URL의 내용을 다양한 형식으로 받아오는 기본 기능입니다.

입력은 크게 네 가지 축으로 구성됩니다. 첫째, 대상 URL. 둘째, 출력 형식 배열로 마크다운, HTML, 링크 목록, 스크린샷 등을 선택합니다. 셋째, 필요 시 API 키를 재정의할 수 있는 옵션. 넷째, 브라우저 세션 옵션입니다.

{
  "url": "https://example.com",
  "outputFormat": ["markdown", "screenshot"],
  "sessionOptions": {
    "useStealth": true,
    "acceptCookies": true
  }
}

실사용 관점에서는 outputFormat을 적절히 조합하는 게 중요합니다.

예를 들어, LLM에 요약이나 분석을 맡길 때는 markdown이 가장 깔끔하고, 링크 구조만 분석하고 싶다면 links, 시각적 확인이 필요하면 screenshot을 함께 요청하는 식입니다.

sessionOptions의 useStealth와 acceptCookies를 켜두면, 기본적인 봇 차단과 쿠키 배너 처리 정도는 신경 쓰지 않고 사용할 수 있습니다.

구조화된 데이터 추출: extract_structured_data

extract_structured_data는 스크래핑된 내용을 "모델이 해석해서 구조화된 JSON으로" 돌려주게 만드는 기능입니다.

핵심 입력은 URL 리스트, 추출 지시 프롬프트, 그리고 선택적인 JSON 스키마입니다.

{
  "urls": ["https://example.com/products/*"],
  "prompt": "Extract product name, price, and description",
  "schema": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "price": { "type": "number" },
      "description": { "type": "string" }
    }
  },
  "sessionOptions": {
    "useStealth": true
  }
}

여기서 중요한 포인트는 두 가지입니다. 하나는 urls에 와일드카드를 쓸 수 있어, 동일 패턴의 여러 페이지를 한 번에 묶어서 처리할 수 있다는 점입니다. 다른 하나는 schema로 AI 출력의 형태를 강제·가이드할 수 있어, 다운스트림 시스템(데이터베이스, 파이프라인, API)과 바로 연동 가능한 구조를 확보할 수 있다는 점입니다.

업무 자동화 시나리오에서는 "스크래핑 + LLM 파싱 + 후속 처리"를 한 번에 감싸는 레이어로 쓰기 좋습니다.

크롤링 자동화: crawl_webpages

crawl_webpages는 하나의 시작 URL에서 여러 페이지를 따라가며 내용을 수집하는 기능입니다.

입력은 시작 URL, 원하는 출력 형식, 링크를 따라갈지 여부, 최대 페이지 수, 사이트맵 무시 옵션, 세션 옵션 등으로 구성됩니다.

{
  "url": "https://example.com",
  "outputFormat": ["markdown", "links"],
  "followLinks": true,
  "maxPages": 5,
  "sessionOptions": {
    "acceptCookies": true
  }
}

followLinks가 true면 해당 페이지의 링크들을 따라가며 순회하게 되고, maxPages로 탐색 범위를 제한합니다.

여기에 ignoreSitemap 옵션을 통해 사이트맵을 무시하도록 설정할 수 있는데, 이는 "사이트맵이 부실하거나, 의도적으로 사이트맵과 다른 동선을 타고 싶을 때" 유용합니다.

실무적으로는 maxPages를 보수적으로 잡고, 크롤링 결과를 보고 URL 패턴을 정제한 뒤 extract_structured_data 쪽으로 넘기는 2단계 전략이 안전합니다.

세션 옵션으로 제어하는 브라우저 행동

모든 도구에는 공통으로 세션 옵션이 있으며, 이는 "브라우저가 어떻게 행동할지"를 제어하는 레버입니다.

useStealth는 자동화 브라우저 탐지를 피하기 위한 설정으로, 헤드리스 티를 줄이는 여러 트릭을 적용합니다.

useProxy는 요청 경로를 프록시로 우회시켜 IP 기반 차단을 피하거나 지역 제한을 우회할 때 사용합니다.

solveCaptchas는 자동으로 CAPTCHA를 해결하려는 시도를 의미하며, 고보안 사이트보다는 간단한 보호 수준의 사이트에서 효과적입니다.

acceptCookies는 쿠키 배너를 자동 처리해 상호작용이 막히는 상황을 줄여줍니다.

업무 자동화 관점에서는 이 옵션들을 "실패율 줄이기 위한 방어선"으로 생각하면 됩니다. 필요한 것만 최소한으로 켜고, 장애가 발생할 때 단계적으로 추가하는 방식이 유지보수에 유리합니다.

인사이트

Hyperbrowser MCP는 "웹 자동화 인프라"를 미리 구현해 둔 뒤, AI와 MCP를 통해 고수준으로 호출하는 구조라서, AI 엔지니어 입장에서 브라우저 제어를 훨씬 덜 의식하고 업무 로직에 집중할 수 있게 해줍니다.

스크래핑 → 구조화 추출 → 크롤링이라는 세 가지 축을 잘 조합하면, 사내 경쟁사 모니터링, 가격 수집, 문서 동기화, 리서치 자동화 같은 워크플로를 거의 코드 없이 MCP 설정 + 프롬프트 설계만으로 설계할 수 있습니다.

실제 적용 시에는

먼저 scrape_webpage로 대상 사이트 특성을 파악하고,
그 결과를 바탕으로 extract_structured_data에 들어갈 프롬프트와 스키마를 설계한 뒤,
마지막으로 crawl_webpages로 규모를 확장하는 순서를 추천합니다. 이렇게 하면 디버깅 비용을 최소화하면서 점진적으로 자동화 범위를 키울 수 있습니다.

출처 및 참고:

https://www.hyperbrowser.ai/docs/integrations/model-context-protocol