Fetcher MCP

Playwright 헤드리스 브라우저를 사용하여 웹 페이지 콘텐츠를 가져오는 MCP 서버입니다.

🌟 추천: OllaMan - 강력한 Ollama AI 모델 관리자.

장점

JavaScript 지원: 기존 웹 스크래퍼와 달리 Fetcher MCP는 Playwright를 사용하여 JavaScript를 실행하므로 동적 웹 콘텐츠와 모던 웹 애플리케이션을 처리할 수 있습니다.
지능형 콘텐츠 추출: 내장된 Readability 알고리즘으로 웹 페이지의 주요 콘텐츠를 자동 추출하여 광고, 네비게이션 등 불필요한 요소를 제거합니다.
유연한 출력 형식: HTML과 Markdown 출력 형식을 모두 지원하여 다양한 다운스트림 애플리케이션과 쉽게 통합할 수 있습니다.
병렬 처리: fetch_urls 도구를 사용하면 여러 URL을 동시에 가져올 수 있어 배치 작업 효율성이 크게 향상됩니다.
리소스 최적화: 불필요한 리소스(이미지, 스타일시트, 폰트, 미디어)를 자동으로 차단하여 대역폭 사용을 줄이고 성능을 개선합니다.
강력한 오류 처리: 포괄적인 오류 처리 및 로깅 기능으로 문제가 있는 웹 페이지를 다룰 때도 안정적인 운영이 가능합니다.
구성 가능한 매개변수: 타임아웃, 콘텐츠 추출 및 출력 형식에 대한 세밀한 제어로 다양한 사용 사례에 맞출 수 있습니다.

빠른 시작

npx로 직접 실행:

npx -y fetcher-mcp

최초 설정 - 터미널에서 다음 명령을 실행하여 필요한 브라우저를 설치하세요:

npx playwright install chromium

HTTP 및 SSE 전송

--transport=http 매개변수를 사용하여 Streamable HTTP 엔드포인트와 SSE 엔드포인트 서비스를 동시에 시작합니다:

npx -y fetcher-mcp --log --transport=http --host=0.0.0.0 --port=3000

시작 후 서버는 다음 엔드포인트를 제공합니다:

/mcp - Streamable HTTP 엔드포인트 (현대식 MCP 프로토콜)
/sse - SSE 엔드포인트 (레거시 MCP 프로토콜)

클라이언트는 필요에 따라 연결 방법을 선택할 수 있습니다.

디버그 모드

--debug 옵션으로 실행하여 디버깅을 위해 브라우저 창을 표시합니다:

npx -y fetcher-mcp --debug

MCP 구성

Claude Desktop에서 이 MCP 서버를 구성하세요:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fetcher": {
      "command": "npx",
      "args": ["-y", "fetcher-mcp"]
    }
  }
}

Docker 배포

Docker로 실행

docker run -p 3000:3000 ghcr.io/jae-jae/fetcher-mcp:latest

Docker Compose로 배포

docker-compose.yml 파일 생성:

version: "3.8"

services:
  fetcher-mcp:
    image: ghcr.io/jae-jae/fetcher-mcp:latest
    container_name: fetcher-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
    # Using host network mode on Linux hosts can improve browser access efficiency
    # network_mode: "host"
    volumes:
      # For Playwright, may need to share certain system paths
      - /tmp:/tmp
    # Health check
    healthcheck:
      test: ["CMD", "wget", "--spider", "-q", "http://localhost:3000"]
      interval: 30s
      timeout: 10s
      retries: 3

그런 다음 실행:

docker-compose up -d

기능

fetch_url - 지정된 URL에서 웹 페이지 콘텐츠 검색
- Playwright 헤드리스 브라우저를 사용하여 JavaScript 파싱
- 주요 콘텐츠의 지능형 추출 및 Markdown 변환 지원
- 다음 매개변수 지원:
  - url: 가져올 웹 페이지의 URL (필수 매개변수)
  - timeout: 페이지 로딩 타임아웃(밀리초), 기본값 30000 (30초)
  - waitUntil: 네비게이션이 완료된 것으로 간주되는 시점 지정, 옵션: 'load', 'domcontentloaded', 'networkidle', 'commit', 기본값 'load'
  - extractContent: 주요 콘텐츠를 지능적으로 추출할지 여부, 기본값 true
  - maxLength: 반환된 콘텐츠의 최대 길이(문자 수), 기본값 제한 없음
  - returnHtml: Markdown 대신 HTML 콘텐츠를 반환할지 여부, 기본값 false
  - waitForNavigation: 초기 페이지 로드 후 추가 네비게이션을 기다릴지 여부(봇 방지 검증이 있는 사이트에 유용), 기본값 false
  - navigationTimeout: 추가 네비게이션을 기다릴 최대 시간(밀리초), 기본값 10000 (10초)
  - disableMedia: 미디어 리소스(이미지, 스타일시트, 폰트, 미디어)를 비활성화할지 여부, 기본값 true
  - debug: 디버그 모드 활성화 여부(브라우저 창 표시), 지정된 경우 --debug 명령줄 플래그를 재정의합니다
fetch_urls - 여러 URL에서 병렬로 웹 페이지 콘텐츠 일괄 검색
- 멀티탭 병렬 가져오기를 사용하여 성능 향상
- 웹페이지 간 명확한 구분으로 결합된 결과 반환
- 다음 매개변수 지원:
  - urls: 가져올 URL 배열 (필수 매개변수)
  - 기타 매개변수는 fetch_url과 동일

팁

특수 웹사이트 시나리오 처리

크롤러 방지 메커니즘 대처

완전한 로딩 대기: CAPTCHA, 리디렉션 또는 기타 검증 메커니즘을 사용하는 웹사이트의 경우 프롬프트에 다음을 포함하세요:
```
페이지가 완전히 로드될 때까지 기다려 주세요
```
이렇게 하면 waitForNavigation: true 매개변수가 사용됩니다.
타임아웃 시간 증가: 로딩이 느린 웹사이트의 경우:
```
페이지 로딩 타임아웃을 60초로 설정해 주세요
```
이렇게 하면 timeout 및 navigationTimeout 매개변수가 그에 따라 조정됩니다.

콘텐츠 검색 조정

원본 HTML 구조 유지: 콘텐츠 추출이 실패할 수 있는 경우:
```
원본 HTML 콘텐츠를 유지해 주세요
```
extractContent: false 및 returnHtml: true로 설정됩니다.
전체 페이지 콘텐츠 가져오기: 추출된 콘텐츠가 너무 제한적인 경우:
```
주요 콘텐츠뿐만 아니라 전체 웹페이지 콘텐츠를 가져와 주세요
```
extractContent: false로 설정됩니다.
HTML 형식으로 콘텐츠 반환: 기본 Markdown 대신 HTML 형식이 필요한 경우:
```
콘텐츠를 HTML 형식으로 반환해 주세요
```
returnHtml: true로 설정됩니다.

디버깅 및 인증

디버그 모드 활성화

동적 디버그 활성화: 특정 가져오기 작업 중 브라우저 창을 표시하려면:
```
이 가져오기 작업에 대해 디버그 모드를 활성화해 주세요
```
이렇게 하면 서버가 --debug 플래그 없이 시작된 경우에도 debug: true로 설정됩니다.

인증을 위한 사용자 정의 쿠키 사용

수동 로그인: 자체 자격 증명을 사용하여 로그인하려면:
```
디버그 모드에서 실행하여 웹사이트에 수동으로 로그인할 수 있도록 해 주세요
```
debug: true를 설정하거나 --debug 플래그를 사용하여 수동 로그인을 위해 브라우저 창을 열어둡니다.
디버그 브라우저와 상호 작용: 디버그 모드가 활성화된 경우:
1. 브라우저 창이 열린 상태로 유지됩니다
2. 자격 증명을 사용하여 웹사이트에 수동으로 로그인할 수 있습니다
3. 로그인이 완료된 후 인증된 세션으로 콘텐츠가 가져와집니다
특정 요청에 대한 디버그 활성화: 서버가 이미 실행 중인 경우에도 특정 요청에 대해 디버그 모드를 활성화할 수 있습니다:
```
이 인증 단계에 대해 디버그 모드를 활성화해 주세요
```
이 특정 요청에 대해서만 debug: true로 설정되어 수동 로그인을 위해 브라우저 창이 열립니다.

개발

종속성 설치

npm install

Playwright 브라우저 설치

Playwright에 필요한 브라우저 설치:

npm run install-browser

서버 빌드

npm run build

디버깅

MCP Inspector를 사용하여 디버깅:

npm run inspector

디버깅을 위해 보이는 브라우저 모드를 활성화할 수도 있습니다:

node build/index.js --debug

라이선스

MIT 라이선스에 따라 라이선스가 부여됩니다.

Translation Not Available Yet