웹 스크래퍼 서비스 (MCP Stdin/Stdout & HTTP)

강력한 헤드리스 웹 스크래핑을 위한 Python 기반 MCP 서버입니다. 웹 페이지에서 주요 텍스트 콘텐츠를 추출하여 AI 및 자동화 통합을 위해 Markdown, 텍스트 또는 HTML로 출력합니다.

주요 기능

• 헤드리스 브라우저 스크래핑 (Playwright, BeautifulSoup, Markdownify)

• Markdown, 텍스트 또는 HTML 출력

• MCP (Model Context Protocol) stdio/JSON-RPC 통합을 위해 설계됨

• 이중 전송: stdio(기본값) 및 공유 서비스 모드를 위한 Streamable HTTP

• 지속적 브라우저 풀: 빠른 스크래핑을 위해 Chromium이 요청 간에도 활성 상태 유지

• 스마트 DOM 대기: 고정된 대기 시간 대신 MutationObserver 기반의 콘텐츠 안정화

• Docker화 및 사전 빌드된 이미지 제공

• 환경 변수를 통한 구성 가능

• 강력한 오류 처리 (타임아웃, HTTP 오류, Cloudflare 등)

• 도메인별 속도 제한

• AI 도구 및 IDE와 쉬운 통합 (Cursor, Claude Desktop, Continue, JetBrains, Zed 등)

• Cursor용 원클릭 설치, Claude용 대화형 설치 프로그램

Related MCP server: Fetcher MCP

빠른 시작

Docker로 실행 (stdio 모드 — 클라이언트당 컨테이너 하나)

docker run -i --rm ghcr.io/justazul/web-scrapper-stdio

공유 HTTP 서비스로 실행 (컨테이너 하나, 여러 클라이언트)

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -e BROWSER_POOL_SIZE=3 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

또는 Docker Compose 사용:

docker compose --profile service up -d

원클릭 설치 (Cursor IDE)

전송 모드

stdio (기본값)

각 MCP 클라이언트는 docker run -i를 통해 자체 컨테이너를 생성합니다. 간단하고 별도의 구성이 필요 없으며 모든 MCP 클라이언트와 작동합니다.

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

Streamable HTTP (공유 서비스)

HTTP를 통해 여러 MCP 클라이언트에 서비스를 제공하는 하나의 지속적인 컨테이너를 실행합니다. 여러 AI 도구 인스턴스(예: 여러 Claude Code 세션)를 실행할 때 리소스를 절약합니다.

서비스 시작:

docker run -d --name web-scraper \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HTTP_PORT=8080 \
  -p 8080:8080 \
  --shm-size=3gb \
  ghcr.io/justazul/web-scrapper-stdio

MCP 클라이언트에서 연결:

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

AI 도구 및 IDE와의 통합

이 서비스는 MCP(Model Context Protocol)를 구현하는 다양한 AI 도구 및 IDE와의 통합을 지원합니다. 아래는 가장 인기 있는 환경에 대한 즉시 사용 가능한 구성 예시입니다. 사용자 지정 빌드에 필요한 경우 이미지/태그를 교체하십시오.

Cursor IDE

.cursor/mcp.json(프로젝트 수준) 또는 ~/.cursor/mcp.json(전역)에 추가:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Desktop

Claude Desktop MCP 구성(claude_desktop_config.json)에 추가:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

Claude Code

.mcp.json 또는 전역 ~/.claude.json에 추가:

stdio 모드 (세션당 컨테이너 하나):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/justazul/web-scrapper-stdio"]
    }
  }
}

HTTP 모드 (공유 서비스 — 먼저 서비스를 시작하세요):

{
  "mcpServers": {
    "web-scrapper": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Continue (VSCode/JetBrains 플러그인)

continue.config.json 또는 Continue 플러그인 MCP 설정에 추가:

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

IntelliJ IDEA (JetBrains AI Assistant)

**Settings > Tools > AI Assistant > Model Context Protocol (MCP)**로 이동하여 새 서버를 추가합니다. 다음을 사용하세요:

{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/justazul/web-scrapper-stdio"
  ]
}

Zed Editor

Zed MCP 구성에 추가 (정확한 경로는 Zed 문서 참조):

{
  "mcpServers": {
    "web-scrapper-stdio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/justazul/web-scrapper-stdio"
      ]
    }
  }
}

사용법

MCP 서버 (도구/프롬프트)

이 웹 스크래퍼는 MCP(Model Context Protocol) 도구로 사용되어 AI 모델이나 기타 자동화 도구에서 직접 사용할 수 있습니다.

도구: scrape_web

매개변수:

• url (문자열, 필수): 스크래핑할 URL

• max_length (정수, 선택): 반환되는 콘텐츠의 최대 길이 (기본값: 제한 없음)

• timeout_seconds (정수, 선택): 페이지 로드 타임아웃(초) (기본값: 30)

• user_agent (문자열, 선택): 브라우저에 직접 전달되는 사용자 지정 User-Agent 문자열 (기본값: 무작위 에이전트)

• wait_for_network_idle (불리언, 선택): 스크래핑 전 네트워크 활동이 안정될 때까지 대기 (기본값: true)

• custom_elements_to_remove (문자열 리스트, 선택): 추출 전 제거할 추가 HTML 요소 (CSS 선택자)

• grace_period_seconds (부동 소수점, 선택): 탐색 후 JS 렌더링을 기다리는 시간. 스마트 감지를 위해 MutationObserver를 사용합니다. 완전히 건너뛰려면 0으로 설정하세요. (기본값: 0.5)

• output_format (문자열, 선택): markdown, text 또는 html (기본값: markdown)

• click_selector (문자열, 선택): 제공된 경우, 탐색 후 추출 전에 이 선택자와 일치하는 요소를 클릭합니다.

반환값:

• 웹 페이지에서 추출된 Markdown 형식의 콘텐츠 (문자열)

• 오류는 [ERROR] ...로 시작하는 문자열로 보고됩니다.

예시: click_selector 및 custom_elements_to_remove 사용

{
  "url": "http://uitestingplayground.com/clientdelay",
  "click_selector": "#ajaxButton",
  "grace_period_seconds": 10,
  "custom_elements_to_remove": [".ads-banner", "#popup"],
  "output_format": "markdown"
}

프롬프트: scrape

매개변수:

• url (문자열, 필수): 스크래핑할 URL

• output_format (문자열, 선택): markdown, text 또는 html (기본값: markdown)

반환값:

• 선택한 형식으로 웹 페이지에서 추출된 콘텐츠

참고:

• 기본적으로 Markdown이 반환되지만 output_format을 통해 텍스트나 HTML을 요청할 수 있습니다.

• 스크래퍼는 robots.txt를 확인하지 않으며 제공된 모든 URL을 가져오려고 시도합니다.

• REST API나 CLI 도구는 포함되어 있지 않으며, 순수 MCP stdio/JSON-RPC 도구입니다.

• 스크래퍼는 항상 웹 페이지의 전체 <body> 콘텐츠를 추출하며, 필수적인 노이즈 제거(script, style, nav, footer, aside, header 및 유사한 비콘텐츠 태그 제거)만 적용합니다. 스크래퍼는 Cloudflare 챌린지 화면을 감지하고 처리하여 특정 오류 문자열을 반환합니다.

구성

환경 변수를 사용하여 대부분의 구성 옵션을 재정의할 수 있습니다:

핵심 설정

• DEFAULT_TIMEOUT_SECONDS: 페이지 로드 및 탐색 타임아웃 (기본값: 30)

• DEFAULT_MIN_CONTENT_LENGTH: 추출된 텍스트의 최소 콘텐츠 길이 (기본값: 100)

• DEFAULT_MIN_CONTENT_LENGTH_SEARCH_APP: search.app 도메인의 최소 콘텐츠 길이 (기본값: 30)

• DEFAULT_MIN_SECONDS_BETWEEN_REQUESTS: 동일한 도메인에 대한 요청 간 최소 지연 시간 (기본값: 2)

• DEFAULT_GRACE_PERIOD_SECONDS: JS 렌더링을 위한 기본 유예 기간 (기본값: 0.5)

• DEBUG_LOGS_ENABLED: 디버그 수준 로그를 활성화하려면 true로 설정 (기본값: false)

브라우저 풀

• BROWSER_POOL_ENABLED: 지속적 브라우저 풀 활성화 (기본값: true). 요청별 브라우저 실행(기존 동작)을 위해 false로 설정하세요.

• BROWSER_POOL_SIZE: 활성 상태로 유지할 Chromium 인스턴스 수 (기본값: 2). 각 인스턴스는 약 100-200MB의 RAM을 사용합니다.

전송

• MCP_TRANSPORT: 전송 모드 — stdio 또는 streamable-http (기본값: stdio)

• MCP_HTTP_PORT: streamable-http 전송 사용 시 HTTP 서버 포트 (기본값: 8080)

• MCP_HTTP_HOST: HTTP 서버 바인딩 주소 (기본값: 0.0.0.0)

Cloudflare 우회

• CAPTCHA_API_KEY: 캡차 해결 서비스용 API 키. 설정 시 Cloudflare Turnstile 챌린지가 자동으로 해결됩니다. 비어 있으면(기본값) CF 보호 페이지는 오류를 반환합니다.

• CAPTCHA_PROVIDER: 캡차 해결 제공자 — 2captcha, capsolver 또는 capmonster (기본값: 2captcha)

• CAPTCHA_BASE_URL: 사용자 지정 해결 API 엔드포인트 (기본값: 제공자의 공식 URL 사용)

• CAPTCHA_TIMEOUT: 캡차 해결 타임아웃(초) (기본값: 120)

테스트 설정

• DEFAULT_TEST_REQUEST_TIMEOUT: 테스트 요청 타임아웃 (기본값: 10)

• DEFAULT_TEST_NO_DELAY_THRESHOLD: 테스트에서 인위적인 지연을 건너뛰기 위한 임계값 (기본값: 0.5)

오류 처리 및 제한 사항

• 스크래퍼는 탐색 실패, 타임아웃, HTTP 오류(404 포함) 및 Cloudflare 봇 방지 챌린지에 대한 오류를 감지하고 반환합니다.

• 속도 제한은 도메인별로 적용됩니다 (기본값: 요청 간 2초).

• Cloudflare 우회: 수동 회피를 위해 Patchright(CDP 수준의 탐지 방지)를 사용합니다. 대부분의 CF 보호 사이트는 챌린지를 트리거하지 않고 스크래핑됩니다. Turnstile 챌린지가 트리거되고 CAPTCHA_API_KEY가 설정된 경우, 타사 API를 통해 자동으로 해결됩니다.

• 제한 사항:

  • REST API나 CLI 도구 없음 (MCP stdio/JSON-RPC 전용)

  • HTML이 아닌 콘텐츠(PDF, 이미지 등) 지원 안 함

  • 보호된 페이지에 대한 인증 또는 세션 관리 없음

  • 대규모 스크래핑이나 사이트 이용 약관 위반을 위한 용도가 아님

개발 및 테스트

테스트 실행 (Docker Compose)

모든 테스트는 Docker Compose를 사용하여 실행해야 합니다. Docker 외부에서 테스트를 실행하지 마십시오.

• 모든 테스트:

docker compose up --build --abort-on-container-exit test

• MCP 서버 테스트만:

docker compose up --build --abort-on-container-exit test_mcp

• 스크래퍼 테스트만:

docker compose up --build --abort-on-container-exit test_scrapper

벤치마크 실행

docker compose run --rm benchmark

결과는 benchmarks/RESULTS.md에 저장됩니다.

기여

기여를 환영합니다! 버그 수정, 기능 추가 또는 개선 사항이 있으면 이슈를 열거나 풀 리퀘스트를 보내주세요. 중요한 변경 사항을 계획 중이라면 먼저 이슈를 열어 제안을 논의해 주십시오.

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.