Crawl-MCP: crawl4ai용 비공식 MCP 서버

⚠️ 중요: 이 프로젝트는 뛰어난 crawl4ai 라이브러리를 위한 비공식 MCP 서버 구현체입니다. 원본 crawl4ai 프로젝트와는 무관합니다.

강력한 crawl4ai 라이브러리를 고급 AI 기능과 결합한 포괄적인 MCP(Model Context Protocol) 서버입니다. 웹 페이지, PDF, Office 문서, YouTube 동영상 등 모든 소스에서 콘텐츠를 추출하고 분석하세요. 지능형 요약 기능을 통해 핵심 정보를 유지하면서 토큰 사용량을 획기적으로 줄일 수 있습니다.

🌟 주요 기능

• 🔍 Google 검색 통합 - Google 공식 연산자를 지원하는 7가지 최적화된 검색 장르

• 🔍 고급 웹 크롤링: JavaScript 지원, 심층 사이트 매핑, 엔티티 추출

• 🌐 범용 콘텐츠 추출: 웹 페이지, PDF, Word, Excel, PowerPoint, ZIP 아카이브

• 🤖 AI 기반 요약: 필수 정보를 보존하면서 토큰을 스마트하게 절감 (최대 88.5%)

• 🎬 YouTube 통합: API 키 없이 동영상 자막 및 요약 추출

• ⚡ 프로덕션 준비 완료: 포괄적인 오류 처리를 갖춘 19가지 전문 도구

Related MCP server: Crawl4AI MCP Server

🚀 빠른 시작

사전 요구 사항 (필수)

• Python 3.11 이상 (FastMCP가 Python 3.11+를 요구함)

Playwright용 시스템 종속성 설치:

Ubuntu 24.04 LTS (수동 설치 필요):

# Manual setup required due to t64 library transition
sudo apt update && sudo apt install -y \
  libnss3 libatk-bridge2.0-0 libxss1 libasound2t64 \
  libgbm1 libgtk-3-0t64 libxshmfence-dev libxrandr2 \
  libxcomposite1 libxcursor1 libxdamage1 libxi6 \
  fonts-noto-color-emoji fonts-unifont python3-venv python3-pip

python3 -m venv venv && source venv/bin/activate
pip install playwright==1.55.0 && playwright install chromium
sudo playwright install-deps

기타 Linux/macOS:

sudo bash scripts/prepare_for_uvx_playwright.sh

Windows (관리자 권한으로 실행):

scripts/prepare_for_uvx_playwright.ps1

설치

UVX (권장 - 가장 쉬움):

# After system preparation above - that's it!
uvx --from git+https://github.com/walksoda/crawl-mcp crawl-mcp

Docker (프로덕션용):

# Clone the repository
git clone https://github.com/walksoda/crawl-mcp
cd crawl-mcp

# Build and run with Docker Compose (STDIO mode)
docker-compose up --build

# Or build and run HTTP mode on port 8000
docker-compose --profile http up --build crawl4ai-mcp-http

# Or build manually
docker build -t crawl4ai-mcp .
docker run -it crawl4ai-mcp

Docker 기능:

• 🔧 멀티 브라우저 지원: Chromium, Firefox, Webkit 헤드리스 브라우저

• 🐧 Google Chrome: 호환성을 위한 추가 Chrome Stable

• ⚡ 최적화된 성능: Docker용으로 사전 구성된 브라우저 플래그

• 🔒 보안: 비루트(Non-root) 사용자 실행

• 📦 완벽한 종속성: 필요한 모든 라이브러리 포함

Claude Desktop 설정

UVX 설치: claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "crawl-mcp": {
      "transport": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/walksoda/crawl-mcp",
        "crawl-mcp"
      ],
      "env": {
        "CRAWL4AI_LANG": "en"
      }
    }
  }
}

Docker HTTP 모드:

{
  "mcpServers": {
    "crawl-mcp": {
      "transport": "http",
      "baseUrl": "http://localhost:8000"
    }
  }
}

일본어 인터페이스용:

"env": {
  "CRAWL4AI_LANG": "ja"
}

📖 문서

언어별 문서

• 영어: docs/ 디렉토리

• 日本語: docs/ja/ 디렉토리

🛠️ 도구 개요

웹 크롤링 (3)

• crawl_url - JavaScript 지원을 통해 웹 페이지 콘텐츠 추출

• deep_crawl_site - 구성 가능한 깊이로 사이트의 여러 페이지 크롤링

• crawl_url_with_fallback - 봇 방지 사이트를 위한 대체 전략으로 크롤링

데이터 추출 (3)

• intelligent_extract - LLM을 사용하여 웹 페이지에서 특정 데이터 추출

• extract_entities - 웹 페이지에서 엔티티(이메일, 전화번호 등) 추출

• extract_structured_data - CSS 선택자 또는 LLM을 사용하여 구조화된 데이터 추출

YouTube (4)

• extract_youtube_transcript - 타임스탬프가 포함된 YouTube 자막 추출

• batch_extract_youtube_transcripts - 여러 YouTube 동영상에서 자막 추출 (최대 3개)

• get_youtube_video_info - YouTube 동영상 메타데이터 및 자막 가용성 확인

• extract_youtube_comments - 페이지 매김을 사용하여 YouTube 동영상 댓글 추출

검색 (4)

• search_google - 장르 필터링을 사용하여 Google 검색

• batch_search_google - 여러 Google 검색 수행 (최대 3개)

• search_and_crawl - Google 검색 후 상위 결과 크롤링

• get_search_genres - 사용 가능한 검색 장르 가져오기

파일 처리 (3)

• process_file - PDF, Word, Excel, PowerPoint, ZIP을 마크다운으로 변환

• get_supported_file_formats - 지원되는 파일 형식 및 기능 확인

• enhanced_process_large_content - 청킹 및 BM25 필터링을 사용하여 대용량 콘텐츠 처리

배치 작업 (2)

• batch_crawl - 대체 전략을 사용하여 여러 URL 크롤링 (최대 3개 URL)

• multi_url_crawl - 패턴 기반 구성으로 다중 URL 크롤링 (최대 5개 URL 패턴)

💾 대용량 결과 디스크 저장 (토큰 절약)

모든 정보 수집 도구는 선택적 output_path 매개변수를 허용합니다. 이 매개변수는 가져온 전체 콘텐츠를 디스크에 직접 쓰고 메타데이터만 포함된 간결한 응답을 반환합니다. 이를 통해 LLM은 컨텍스트 제한을 초과하지 않고도 거대한 페이지, 긴 YouTube 자막 또는 전체 배치를 가져올 수 있으며, 필요할 때만 저장된 파일에서 읽어올 수 있습니다.

작동 방식:

• 단일 파일 도구(예: crawl_url, extract_youtube_transcript)는 하나의 .md(또는 JSON 도구의 경우 .json) 파일을 씁니다. 절대 경로를 전달하세요. 확장자가 생략되면 자동으로 추가됩니다. 해당 경로에 기존 일반 파일이 있는 경우 overwrite=true가 아니면 거부됩니다.

• 배치 도구(batch_crawl, multi_url_crawl, deep_crawl_site, search_and_crawl, batch_extract_youtube_transcripts)는 절대 디렉토리 경로를 예상하며 URL당 하나의 .md 파일과 index.json을 씁니다. 존재하지 않는 경로는 디렉토리로 간주되어 생성됩니다(점(.)이 포함된 이름 포함, 예: /tmp/run.v1). 경로가 이미 일반 파일로 존재하는 경우 호출이 거부됩니다. batch_crawl / multi_url_crawl은 list 반환 형태를 유지하며 각 성공 항목에 output_file 키를 포함합니다.

• 요청 딕셔너리 도구(search_google, batch_search_google, search_and_crawl, batch_extract_youtube_transcripts)는 요청 딕셔너리에서 직접 지속성 키를 읽습니다.

• 공통 매개변수: output_path(절대 경로; None 또는 ""는 저장 건너뜀), include_content_in_response(기본값 false — true일 경우 응답에 콘텐츠가 포함됨, 여전히 content_limit/content_offset/max_content_per_page 슬라이싱 적용), overwrite(기본값 false).

• 쓰기는 파일 단위로 원자적(임시 파일 + os.replace)으로 수행됩니다. 상위 디렉토리는 자동으로 생성됩니다. 전체 슬라이싱되지 않은 페이로드는 슬라이싱이나 도구 내부의 잘림이 발생하기 전에 저장되므로 응답이 슬라이싱되더라도 디스크 복사본은 항상 완전합니다.

• 배치 딕셔너리 도구(deep_crawl_site, search_and_crawl, batch_extract_youtube_transcripts)는 success=false를 보고하는 항목에 대해 항목별 저장을 건너뜁니다. 이 항목들은 호출자가 시도 목록을 파악할 수 있도록 file: null과 함께 index.json에 계속 표시됩니다.

마크다운 단일 파일 예시:

{
  "tool": "crawl_url",
  "arguments": {
    "url": "https://example.com/long-article",
    "output_path": "/tmp/crawl_out/article.md"
  }
}

JSON 구조화된 추출 (확장자 자동 추가):

{
  "tool": "extract_structured_data",
  "arguments": {
    "url": "https://example.com/products",
    "extraction_type": "css",
    "css_selectors": {"price": ".price", "name": "h1"},
    "output_path": "/tmp/crawl_out/products"
  }
}

배치 디렉토리 모드:

{
  "tool": "batch_crawl",
  "arguments": {
    "urls": ["https://a.example", "https://b.example"],
    "output_path": "/tmp/crawl_out/batch_run1"
  }
}

각 저장된 마크다운 파일은 url, title, fetched_at, source_tool이 포함된 YAML 프론트매터 블록으로 시작하여 아티팩트가 자체적으로 설명되도록 합니다.

🎯 일반적인 사용 사례

콘텐츠 조사:

search_and_crawl → extract_structured_data → analysis

문서 마이닝:

deep_crawl_site → batch processing → extraction

미디어 분석:

extract_youtube_transcript → summarization workflow

사이트 매핑:

batch_crawl → multi_url_crawl → comprehensive data

🚨 빠른 문제 해결

설치 문제:

1. 적절한 권한으로 설치 스크립트를 다시 실행하세요.

2. 개발 설치 방법을 시도하세요.

3. 브라우저 종속성이 설치되었는지 확인하세요.

성능 문제:

• JavaScript가 많은 사이트의 경우 wait_for_js: true를 사용하세요.

• 로딩이 느린 페이지의 경우 타임아웃을 늘리세요.

• 타겟팅된 추출을 위해 extract_structured_data를 사용하세요.

구성 문제:

• claude_desktop_config.json의 JSON 구문을 확인하세요.

• 파일 경로가 절대 경로인지 확인하세요.

• 구성 변경 후 Claude Desktop을 다시 시작하세요.

🏗️ 프로젝트 구조

• 원본 라이브러리: unclecode의 crawl4ai

• MCP 래퍼: 이 저장소 (walksoda)

• 구현: 비공식 타사 통합

📄 라이선스

이 프로젝트는 crawl4ai 라이브러리를 감싸는 비공식 래퍼입니다. 기본 기능에 대해서는 원본 crawl4ai 라이선스를 참조하십시오.

🤝 기여

기여 지침 및 개발 설정 지침은 개발 가이드를 참조하십시오.

🔗 관련 프로젝트

• crawl4ai - 기본 웹 크롤링 라이브러리

• Model Context Protocol - 이 서버가 구현하는 표준

• Claude Desktop - MCP 서버의 기본 클라이언트