Scrapling 설치 가이드: Cloudflare에 안 막히는 스크래퍼를 Claude Code에 붙이기

스크래퍼를 만들면 두 번 막힌다. 한 번은 사이트 구조가 바뀔 때, 또 한 번은 봇 검사에 걸릴 때다. 특히 Cloudflare 봇 검사(“Just a moment…”)에 걸리면 코드가 아무리 멀쩡해도 403만 돌아온다.

Scrapling은 이 두 번째 벽을 넘는 파이썬 오픈소스다. 이 글은 설치, Cloudflare 통과, Claude Code·Codex에 MCP로 붙이는 것까지 직접 돌려본 순서대로 정리했다.

D4VinciScraplingRepository

BSD-3-Clause · GitHub 스타 83,815개 · 최신 v0.4.15 (2026-09-26 기준)

직접 돌려본 결과

같은 Cloudflare 테스트 페이지(nopecha.com/demo/cloudflare)를 세 가지 방법으로 요청했다.

방법	결과
일반 요청 (curl)	403
Scrapling StealthyFetcher, 옵션 없이	403 (“Just a moment…”)
Scrapling StealthyFetcher, solve_cloudflare=True	200, 실제 페이지

통과까지 약 48초 걸렸다. 빠르지는 않다. 대신 사람이 봇 검사를 풀어줄 필요가 없다.

판단: 핵심은 solve_cloudflare=True 옵션이다. 이걸 안 켜면 Scrapling도 똑같이 막힌다.

“700배 빠르다”는 무슨 뜻인가

README의 벤치마크는 파싱(HTML에서 텍스트 뽑기) 속도다. 요소 5,000개짜리 문서 기준으로 이렇다.

라이브러리	시간(ms)	Scrapling 대비
Scrapling	1.99	1.0x
Parsel/Scrapy	2.06	1.035x
lxml	2.56	1.29x
BeautifulSoup + lxml	1562.1	약 785x

BeautifulSoup으로 짜고 있었다면 체감이 크다. Scrapy를 쓰고 있었다면 속도 차이는 거의 없다. 네트워크 대기 시간은 이 숫자에 포함되지 않는다.

D4Vinci/Scraplingbenchmarks.pymainPython

1. 설치

파이썬 3.10 이상이 필요하다. 먼저 버전부터 본다.

python3 --version

함정: 맥 기본 python3 은 3.9 다

macOS 에 기본으로 들어 있는 python3(/usr/bin/python3)는 3.9 다. 이걸로 가상환경을 만들면 pip install "scrapling[ai]" 가 설치할 버전을 못 찾고 실패한다. 직접 해보니 실제로 그랬다.

3.10 이상이 없으면 Homebrew 로 깐다(brew install python@3.12). 그다음 버전을 찍어서 가상환경을 만든다.

python3.12 -m venv ~/.venvs/scrapling
source ~/.venvs/scrapling/bin/activate

pip install "scrapling[ai]"   # MCP 서버까지 포함
scrapling install             # 브라우저 설치 (약 13초)

함정: scrapling install을 빼먹으면 안 돈다

pip install scrapling만 하면 파서만 깔린다. Cloudflare를 넘는 fetcher는 브라우저가 따로 필요하다. README도 이걸 경고한다. extras([ai], [fetchers], [all])를 뭘 깔든 scrapling install은 한 번 돌려야 한다.

2. 파이썬에서 Cloudflare 넘기

from scrapling.fetchers import StealthyFetcher

page = StealthyFetcher.fetch(
    "https://nopecha.com/demo/cloudflare",
    headless=True,
    solve_cloudflare=True,
)
print(page.status)                    # 200
print(page.css("title::text").get())  # 실제 페이지 제목

여러 페이지를 연달아 가져올 거면 브라우저를 계속 띄워두는 세션을 쓴다.

from scrapling.fetchers import StealthySession

with StealthySession(headless=True, solve_cloudflare=True) as session:
    page = session.fetch("https://nopecha.com/demo/cloudflare", google_search=False)
    links = page.css("#padded_content a").getall()

3. Claude Code에 붙이기

MCP 서버 실행 파일 경로를 먼저 찾는다.

which scrapling-mcp

그 경로로 등록한다.

claude mcp add ScraplingServer "$(which scrapling-mcp)"
claude mcp list    # ScraplingServer ... ✔ Connected

이제 Claude Code에 이렇게 말하면 된다.

Scrapling으로 https://nopecha.com/demo/cloudflare 가져와줘. Cloudflare 해제 옵션 켜고.

직접 해보니 Claude Code가 stealthy_fetch 도구를 solve_cloudflare=true로 호출해서 페이지 제목과 본문을 받아왔다. MCP를 거치면 전체 1분 조금 넘게 걸렸다.

판단: 처음부터 “Cloudflare 해제 옵션 켜고”라고 말해주는 게 낫다. 옵션이 꺼진 채로 먼저 시도하면 403을 한 번 받고 돌아간다.

4. Codex에 붙이기

codex mcp add ScraplingServer -- "$(which scrapling-mcp)"
codex mcp list

등록까지는 확인했다. Codex에서 실제로 Cloudflare 페이지를 가져오는 것까지는 이 글에서 검증하지 않았다.

한계

• Cloudflare 봇 검사(Turnstile)까지다. Akamai, DataDome, Kasada 같은 기업용 방어는 README도 별도 유료 서비스를 안내한다. “어떤 사이트든 뚫린다”가 아니다.
• 느리다. 해제 옵션을 켜면 한 페이지에 수십 초가 걸린다. 대량 수집이면 세션을 재사용하고, 막히지 않는 사이트는 일반 Fetcher를 쓴다.
• 사이트 약관과 robots.txt는 여전히 지켜야 한다. 기술적으로 넘을 수 있다는 것과 가져가도 된다는 것은 다른 문제다.

참고

• MCP 서버 공식 문서: https://scrapling.readthedocs.io/en/latest/ai/mcp-server.html
• 설치 문서: README의 Installation 섹션