cute-web-scraper

Claude에 웹 스크래핑 기능을 제공하는 MCP 서버. 무료, 로컬 실행, API 키 불필요, 클라우드 계정 불필요.

평범한 영어로 요청하세요. 페이지를 가져오고, 필요하면 JavaScript를 렌더링하고, 차단을 우회한 뒤, 깔끔한 마크다운이나 쿼리 가능한 테이블로 돌려줍니다 — 셀렉터도, 글루 코드도 필요 없습니다.

왜 이걸 써야 하나

• 들어갑니다. 4단계로 강화되는 계층 — 일반 HTTP, 브라우저 TLS 지문, 실제 브라우저, 그다음 스텔스 브라우저. ASOS, eBay, Booking.com, Trustpilot 모두 프록시 없이 일반 가정용 연결에서 실제 데이터를 반환합니다.

• 컨텍스트를 낭비하지 않습니다. 기사에서 내비게이션, 쿠키 배너, 푸터를 제거합니다: BBC 뉴스 페이지가 20,513자에서 3,198자로 줄어듭니다. 대용량 결과는 SQL로 쿼리하는 SQLite 테이블에 저장되므로 채팅에 붙여넣을 필요가 없습니다.

• 실패에 대해 정직합니다. 테스트한 사이트 중 5곳이 성공 상태 코드 아래에서 거부를 응답했습니다 — HTTP 200 아래의 인터스티셜, 202 아래의 봇 검사 — 그리고 한 곳은 403 아래에서 실제 콘텐츠를 제공했습니다. 차단 감지는 상태 코드가 아닌 페이지 본문을 기준으로 판단하므로, 스텁을 데이터로 보고받는 일이 없습니다.

• 단일 페이지가 아닌 전체 사이트. 사이트맵 탐색, 병렬 페칭, 제품·연락처·Shopify 카탈로그·장소·PDF·변경 추적을 다루는 24개 도구.

설치

pipx install git+https://github.com/maccydee/cute-web-scraper

Chromium은 js_render를 처음 사용할 때 자동으로 다운로드됩니다(일회성 약 130MB).

Related MCP server: mcp-server-scraper

Claude Code에 연결

claude mcp add cute-web-scraper -- cute-web-scraper

그런 다음 그냥 요청하세요:

Scrape every product from https://example-shop.com and give me a CSV of name and price.

도구

페칭 및 탐색

추출

장소 및 지역 업체

변경 추적

결과 테이블

일반적인 실행은 이들을 조합합니다: analyze_website → crawl_site → fetch_pages → query_table.

임의 필드 추출

extract_by_selector는 고정 추출기가 다루지 못하는 모든 것을 처리합니다:

Get the title, price and link from every product on these 40 pages,
save it as `catalogue`, then show me anything under £50.

fields는 열 이름을 CSS 셀렉터에 매핑합니다. row_selector는 각 일치 항목을 행으로 만듭니다 — 이것이 목록을 테이블로 바꾸는 핵심입니다. @attr 접미사는 텍스트 대신 속성을 읽으며, href와 src는 절대 URL로 변환됩니다:

{"name": "h3 a@title", "price": ".price_color", "link": "h3 a@href"}

페이지 조작

fetch_page는 페이지를 읽기 전에 실행되는 actions를 받습니다 — 쿠키 게이트, "더 보기" 버튼, 무한 스크롤, 검색 폼:

[{"action": "click", "selector": "#accept-cookies"},
 {"action": "scroll_to_bottom", "max_rounds": 10}]

사용 가능한 액션: click, type, press, wait, wait_for, scroll, scroll_to_bottom, click_until_gone. 각 액션은 수행한 작업을 보고하므로, 조용히 아무것도 일치하지 않은 단계도 추측에 맡기지 않고 확인할 수 있습니다.

페이지 대신 API 읽기

사이트를 파싱하기 어려울 때 inspect_network는 페이지를 렌더링하고 페이지가 만든 요청을 보고합니다. JavaScript 페이지는 거의 항상 직접 가져올 수 있는 엔드포인트에서 데이터를 로드합니다 — 마크업을 파싱하는 것보다 저렴하고, 셀렉터를 깨뜨리는 리디자인에도 견딥니다:

Inspect the network on this listing page, then fetch whatever JSON endpoint it uses.

변경 감시

Check https://example.com/pricing for changes.

track_changes는 스냅샷을 저장하고 통합 diff와 함께 new, same 또는 changed를 보고합니다. 스케줄러 없이 모니터링하는 셈입니다 — 원할 때마다 확인하고 차이만 보면 됩니다.

슬래시 명령

서버에는 4개의 준비된 워크플로우가 포함되어 있으며, Claude Code에서 슬래시 명령으로 나타납니다: scrape_site, scrape_shopify_store, find_contacts, compare_prices.

대규모 스크래핑 작업

행을 반환하는 모든 도구는 save_as를 받습니다. 데이터를 대화에 넣는 대신 결과 테이블을 작성하고 요약을 돌려줍니다:

Extract the whole catalogue from deathwishcoffee.com into a table called `catalogue`,
then tell me the price range and how many variants are out of stock.

Claude는 extract_shopify_store(save_as="catalogue")를 호출하고 행 수와 열 목록을 받은 다음, query_table로 답변합니다:

SELECT COUNT(*) AS variants, MIN(price) AS cheapest,
       MAX(price) AS dearest, SUM(available) AS in_stock
FROM catalogue

테이블은 100,000행을 담을 수 있으며 그중 어떤 것도 대화에 들어가지 않습니다. query_table은 엄격히 읽기 전용입니다 — 읽기 전용 SQLite 핸들로 실행되며 SELECT가 아닌 것은 모두 거부하므로, 쿼리가 저장된 데이터를 수정하거나 삭제할 수 없습니다.

테이블은 ~/.cute-web-scraper/results.db의 SQLite 파일에 저장됩니다(SCRAPER_DB_PATH로 위치 변경 가능).

데이터 정리

query_table도 save_as를 받으며, 결과를 새 테이블로 저장합니다. SQL이 일반적인 정리 작업을 이미 표현하므로 별도의 편집 도구 세트는 없습니다:

SELECT DISTINCT * FROM leads                                  -- deduplicate
SELECT street || ', ' || city AS address FROM leads           -- merge columns
SELECT name, phone FROM leads WHERE phone IS NOT NULL         -- drop columns and rows
SELECT vendor AS brand FROM catalogue                         -- rename

원본 테이블은 의도적으로 자신의 이름을 대상으로 하지 않는 한 그대로 유지되며, 그렇게 할 때 응답에 replaced_existing_table이 표시됩니다 — 따라서 제자리 필터가 조용히 행을 잃는 일은 없습니다.

장소 및 지역 업체

find_places는 단일 장소를 조회하고, find_places_nearby는 반경 내 특정 카테고리의 모든 항목을 반환합니다 — 이것이 지역 리드 생성 사례입니다:

Find every dentist within 4km of Bath, save it as `leads`,
then tell me how many have a website but no phone number.

카테고리는 친숙한 이름(cafe, dentist, hotel, solicitor, gym, hairdresser, …) 또는 amenity=dentist 같은 원시 OpenStreetMap 태그를 허용합니다.

데이터 소스에 대한 참고. 이것은 OpenStreetMap이지 Google Maps가 아닙니다. Google이 당연한 목표였지만 작동하지 않습니다: 자동화된 브라우저는 쿠키 동의 인터스티셜을 만나고, 그걸 넘어가면 장소 패널이 없는 저하된 지도 셸만 얻습니다. 스텔스 계층도 도움이 되지 않는데, 이는 봇 감지가 아닌 동의 벽(consent wall)이기 때문입니다 — 스텔스가 해결하는 문제와는 다른 문제입니다.

OpenStreetMap은 문서화된 공개 엔드포인트를 통해 키 없이 동일한 필드(이름, 주소, 좌표, 전화, 웹사이트, 영업시간, 카테고리)를 제공합니다. 유일하게 대응하는 것이 없는 것은 별점 평점과 리뷰 수인데, 이는 Google의 독점 데이터입니다.

두 엔드포인트 모두 자원봉사로 운영됩니다. Nominatim의 초당 1회 요청 정책은 SCRAPER_DELAY_MS와 무관하게 내부적으로 강제되며, Overpass 쿼리는 여러 공개 미러를 통해 전달되는데, 메인 인스턴스가 부하 시 정기적으로 504를 반환하기 때문입니다.

도구 출력도 SCRAPER_MAX_INLINE_CHARS(기본 25,000)로 제한됩니다. 이를 초과하면 결과가 잘리고 save_as를 가리키는 메모가 함께 표시됩니다 — 따라서 단일 호출이 실수로 컨텍스트를 가득 채울 수 없습니다.

예시 프롬프트

Export the whole catalogue from deathwishcoffee.com and tell me the price range.

Find all email addresses on https://company.com and its contact pages.

What platform is https://myblog.com on? Does it need JavaScript to scrape?

Scrape these 200 product pages into a table, then show me everything under £50 that's in stock.

Extract the social media links from these 10 agency sites: [urls...]

구성

모든 것이 환경 변수이며, 기본값은 설정 없이도 작동합니다.

긴 URL 목록을 하나의 테이블로 배치하려면 첫 호출 이후의 모든 호출에서 mode: "append"가 필요합니다. 그렇지 않으면 각 배치가 이전 배치를 대체합니다. 희소하게 반환되는 렌더링 페이지에는 wait_ms를 지정하거나, 더 나은 방법으로 CSS 선택자와 함께 wait_for를 지정할 수 있습니다.

동작 방식

전체 페이지가 아닌 본문 콘텐츠. 기사 형태의 페이지는 trafilatura를 통해 처리되며, 본문을 분리하고 주변 요소를 제거합니다. 독립적인 2,008페이지 벤치마크에서 Readability의 0.674 대비 0.791 F1 점수를 기록했기 때문에 선택되었습니다. 이는 모든 페이지에 적용되는 것이 아니라 페이지별로 적용됩니다. 동일한 벤치마크에서 제품 그리드와 컬렉션에서는 추출기가 20~30포인트 차이를 보이는데, 여기서 "본문 콘텐츠"는 기사가 아니므로 목록 페이지는 전체 문서를 유지합니다. 어디서든 강제로 적용하려면 main_content: false를 전달하세요.

거부될 때만 단계적으로 상승하는 4단계. 일반 HTTP 클라이언트가 대부분의 페이지를 처리합니다. 사이트가 거부하면 요청이 실제 브라우저 TLS 지문(Chrome, 그다음 Safari)으로 재시도됩니다. 일부 사이트는 TLS 핸드셰이크 자체를 지문으로 사용하며 어떤 헤더 변경으로도 통과할 수 없기 때문입니다. js_render: true는 단일 페이지 앱을 위해 Chromium에서 렌더링합니다. 최후의 수단으로, JavaScript가 필요하고 일반 자동화를 거부하는 사이트를 위해 스텔스 패치된 브라우저가 처리합니다.

각 단계는 서로 다른 실패를 해결하며, 어떤 단계도 다른 단계의 상위 집합이 아닙니다. TLS 단계는 JavaScript를 실행할 수 없고, Playwright는 탐지 가능한 자동화 브라우저입니다. 모든 결과는 어떤 단계가 처리했는지 보고합니다. SCRAPER_IMPERSONATE=0 또는 SCRAPER_STEALTH=0을 설정하면 마지막 두 단계를 끄고 차단이 그대로 유지되도록 할 수 있습니다.

마지막 두 단계는 예의가 아니라 회피입니다. 사이트가 의도적으로 배포한 봇 탐지를 통과하기 위해 존재합니다. 이들은 정상적으로 페이지를 제공한 사이트에서는 절대 실행되지 않고, 거부된 후에만 실행됩니다.

적응형 백오프. 동일 도메인에 대한 요청은 SCRAPER_DELAY_MS 간격으로 시작 시점 기준으로 측정되므로, 지연 시간이 느린 응답에 추가되는 것이 아니라 요청 속도를 제한합니다. 도메인이 429, 403, Cloudflare 챌린지 등으로 반발하면 해당 도메인의 지연 시간이 최대 60초까지 두 배로 증가하고, 요청이 다시 성공하면 감소합니다. 도메인은 독립적으로 추적되므로 두 사이트를 동시에 스크래핑해도 추가 비용이 들지 않습니다.

robots.txt는 강제되지 않습니다. 사이트맵을 찾는 데만 읽히며, Disallow 규칙은 참조되지 않고 이를 변경할 설정도 없습니다. 적응형 도메인별 지연 시간이 이 도구의 예의 메커니즘입니다.

짧은 캐시. 가져온 페이지는 5분 동안 재사용되므로 동일한 URL에 대해 fetch_pages를 실행한 후 extract_emails를 실행해도 모든 것을 두 번 가져오지 않습니다.

HTTP 모드

기본값은 stdio이며, 위의 claude mcp add가 사용하는 방식입니다. 대신 지속적인 공유 인스턴스를 실행하려면:

SCRAPER_AUTH_TOKEN=$(openssl rand -hex 16) cute-web-scraper --http --port 8080

claude mcp add --transport http cute-web-scraper http://127.0.0.1:8080/mcp

127.0.0.1에 바인딩되며 /mcp와 /health 엔드포인트를 노출합니다. 루프백을 넘어 어디든 바인딩하려면 SCRAPER_AUTH_TOKEN이 필요하며, 서버는 토큰 없이 네트워크에 공개 스크래퍼를 조용히 게시하는 대신 시작을 거부합니다.

제한 사항

• 프록시 순환과 CAPTCHA 해결이 없습니다. 4단계를 모두 통과하지 못한 사이트는 추측하지 않고 차단된 것으로 보고됩니다.

• LinkedIn 및 유사 사이트는 로그인된 Chrome 프로필을 가리키는 SCRAPER_CHROME_USER_DATA_DIR이 필요할 수 있습니다.

• SCRAPER_DELAY_MS=0은 예의 지연을 제거하지만, 사이트가 반발하면 백오프는 여전히 작동합니다.

• 전화번호 추출은 의도적으로 보수적입니다. 국가 코드 또는 국번 접두사가 필요하므로 일부 기본 로컬 형식을 놓치지만, 연도와 주문 번호를 반환하지는 않습니다.

개발

uv sync --extra dev

uv run pytest -v

uv run pytest -m integration -v -s

uv run ruff check src/ tests/ && uv run mypy src/cute_web_scraper/

단위 테스트는 밀폐되어 있으며 네트워크에 접촉하지 않습니다. 통합 테스트는 실제 사이트에 접속하며 기본 실행에서 제외됩니다.

라이선스

MIT — LICENSE 참조.