fast-webfetch-mcp

웹 페이지를 실제 브라우저로 렌더링한 후, 모델에게 2MB JavaScript의 토큰 청구서 대신 깔끔한 Markdown을 전달하는 웹 페칭 MCP 서버입니다.

여기서 페칭은 비용이 들지 않습니다: API 키도, 페이지당 요금도 없습니다. 그리고 사이트가 차단한다고 주장할 때, 종종 그냥 headless 탐지 스크립트일 뿐이며 실제 Chromium은 그냥 통과합니다.

작동 방식

두 개의 작은 프로그램, 하나의 작업:

MCP client (agent)
   │  JSON-RPC over stdio
   ▼
src/index.ts          Bun + MCP SDK — tool schemas, budgets, rendering
   │  spawns per request
   ▼
crawl4ai_worker.py    Python + Crawl4AI — headless Chromium, markdown extraction
   │
   ▼
The actual internet

TypeScript 서버는 정책을 담당합니다: 타임아웃, 동시성 허용량, 출력 잘라내기, 선택적 Gemini 기반 요약. Python 워커는 메커니즘을 담당합니다: 브라우저 수명 주기, 렌더링, 재시도. 서로의 작업을 알지 못하며, 둘 사이의 계약은 stdout의 JSON 문서 하나입니다.

Related MCP server: crawler-mcp

설치

요구 사항: Bun, Python 3.12+, 그리고 첫 브라우저 다운로드를 위한 GPU와 무관한 인내심.

git clone <this repo> ~/.local/share/mcp/fast-webfetch-mcp   # or anywhere
cd ~/.local/share/mcp/fast-webfetch-mcp
bun install
uv venv .venv --python 3.12 && uv pip install --python .venv/bin/python crawl4ai

브라우저 쪽이 작동하는지 확인:

FAST_WEBFETCH_SMOKE_URL=https://example.com bun run src/index.ts

예제 도메인에 대한 Markdown이 보여야 합니다. 대신 Playwright 브라우저에 대한 스택 트레이스가 보이면, venv에서 crawl4ai-setup을 실행하고 다시 시도하세요 — 올바른 Chromium 빌드를 설치해 줍니다.

에이전트에 연결하기

{
  "mcpServers": {
    "fast-webfetch": {
      "type": "stdio",
      "command": "/usr/bin/mullvad-exclude",
      "args": ["/home/you/.bun/bin/bun", "run", "/path/to/fast-webfetch-mcp/src/index.ts"],
      "env": { "PATH": "/home/you/.bun/bin:/usr/bin:/bin" }
    }
  }
}

mullvad-exclude 래퍼는 선택 사항입니다; 단지 페치 트래픽이 VPN을 우회하여 사이트가 실제 IP를 보게 합니다. 일반 "command": "bun"도 동일하게 작동합니다.

도구

fast_fetch — URL 하나를 Markdown으로

fast_fetch_raw — URL 하나를 원시 HTML로

prompt를 제외한 동일한 인자. Markdown이 필요한 것을 잃을 때 사용하세요: 테이블, data- 속성, 메타 태그, 정확한 마크업.

options 객체

세 도구 모두 선택적 options 객체를 허용하며, 단순 로드-앤-그랩 이상이 필요한 사이트용입니다:

{
  "url": "https://example.com/feed",
  "options": { "full_page": true, "wait_seconds": 1.5, "drop_overlays": true }
}

오타가 있는 키는 전달되지 않고 조용히 버려집니다 — options 페이로드는 Python 쪽에서 CrawlerRunConfig 플래그가 됩니다.

fast_fetch_multiple — 한 번에 최대 15개 URL

각 URL은 메타데이터 헤더(url, status, elapsed_ms, truncated)와 함께 자체 섹션으로 반환됩니다. 느린 사이트 하나가 다른 사이트를 굶기지 않습니다 — 항목별 타임아웃 오류만 받고 배치 동료는 성공합니다.

구성

모두 선택 사항, 모두 환경 변수.

서버 설정

브라우저 설정

알아두면 좋은 동작

JS가 많은 사이트는 기본 대기 전략에서 빈 껍데기를 반환하는 경우가 많습니다. 200이 콘텐츠 없이 돌아오면 워커는 동일한 타임아웃 예산 내에서 networkidle로 한 번 재시도합니다 — 최악의 경우 한 번 기다리지 두 번 기다리지 않습니다. 연결 실패와 HTTP 오류는 한 번만 시도합니다: 죽은 호스트를 재시도하는 것은 더 느리게 실패하는 방법일 뿐입니다.

fast_fetch와 fast_fetch_multiple은 동일한 12개 브라우저 슬롯 풀을 사용하므로 큰 배치가 동시 단일 페치를 굶기지 않습니다. 풀을 초과하는 수요는 대기열에 들어가고, 존재하는 슬롯보다 더 많은 슬롯을 요청하는 배치는 사용 가능한 것을 얻습니다.

마지막으로, max_length는 에이전트의 컨텍스트 창이 예산이지 쓰레기 매립지가 아니기 때문에 존재합니다.

문제 발생 시 로그 경로를 얻습니다

실패는 두 가지로 분류됩니다: 인터넷이 불안정한 경우(타임아웃, 느린 사이트, 항목별 배치 마감 오류)와 도구가 실제로 고장난 경우(워커가 시작되지 않음, 워커 충돌, stdout 오버플로, 구문 분석 불가 출력). 두 번째 경우에만 로그가 기록됩니다 — 첫 번째는 정직한 오류 태그만 받습니다.

도구 측 실패는 다음으로 끝납니다:

log: /path/to/fast-webfetch-mcp/logs/2026-08-22T09-02-06-780Z-fast_fetch.json

내부: 도구, 정확한 인자, 워커 입력, 전체 실패 기록(단계, 종료 코드, 시그널, stderr 꼬리) — 요청을 그대로 재생하기에 충분합니다:

FAST_WEBFETCH_INPUT='{"url":"https://example.com","max_length":40000}' \
  .venv/bin/python crawl4ai_worker.py

FAST_WEBFETCH_LOGS_DIR로 리디렉션하세요.

30초 미만 유지

에이전트 하네스는 MCP 호출을 약 30초 지점에서 종료하는 경향이 있으므로 이 서버는 28초를 하드 벽으로 취급합니다. 모든 도구는 그 전에 응답합니다: 페치가 성공하면 완료된 결과, 그렇지 않으면 어떤 단계가 시간을 소비했는지 말하는 구조화된 항목별 오류. 예산이 소진된 배치도 완료된 항목은 반환합니다.

문제 해결

개발

bun install
bun test            # 18 tests, no network needed
bun run typecheck   # tsc --noEmit, strict + noUncheckedIndexedAccess

Python 워커는 직접 구동할 수 있으며, MCP 레이어 없이 페치 동작을 디버깅하는 가장 빠른 방법입니다:

FAST_WEBFETCH_INPUT='{"url":"https://example.com","max_length":500}' \
  .venv/bin/python crawl4ai_worker.py

참고

• ddg-search — 자연스러운 프론트 엔드: 검색 후 결과 URL을 이 서버에 전달

• Crawl4AI — 기반이 되는 크롤링 엔진

• Model Context Protocol — 와이어 프로토콜

라이선스

MIT.