@trishchuk/mcp-fetch-server

AI 에이전트(Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Antigravity 등)를 위한 안티봇 방어 기능을 갖춘 fetch 도구를 제공하는 고성능 Model Context Protocol (MCP) 서버입니다.

@trishchuk/fetch를 기반으로 구동되며, 실제 브라우저의 TLS (JA3/JA4, ClientHello) 및 HTTP/2 핑거프린트를 정확하게 모방하는 네이티브 curl-impersonate 스타일 HTTP 클라이언트입니다.

🚀 이 서버를 사용해야 하는 이유는?

표준 Node.js/Undici HTTP 클라이언트는 최신 봇 보호 시스템(Cloudflare Turnstile / Under Attack Mode, DataDome, PerimeterX / HUMAN, Akamai, Kasada, AWS WAF)에 의해 즉시 감지되어 차단됩니다.

또한, 표준 MCP 페칭 도구는 대용량 페이로드에서 자주 실패하거나 LLM 토큰 컨텍스트를 폭발시킵니다.

@trishchuk/mcp-fetch-server는 두 가지 문제를 모두 해결합니다:

1. 현실적인 브라우저 가장: 최신 브라우저(Chrome, Safari, Firefox)의 정확한 암호 제품군, TLS 확장, ALPN 순서 및 HTTP/2 설정 프레임을 복제합니다.

2. LLM 컨텍스트 안전 잘림: 응답 본문을 2MB(maxResponseBytes)로 스트리밍하고 제한합니다. 초과하는 큰 페이지는 오류와 함께 중단되는 대신 깔끔하게 잘리고 "truncated": true로 표시됩니다.

3. 상태 저장 세션: session 매개변수를 사용하여 여러 에이전트 도구 호출 간에 쿠키, 로그인 상태 및 연결 풀을 유지합니다.

4. 스마트 인코딩: MIME 유형을 자동 감지하여 HTML/JSON/XML의 경우 깨끗한 UTF-8 텍스트를, 바이너리 파일(이미지, PDF, 문서)의 경우 Base64를 반환합니다.

Related MCP server: webfetch-mcp

✅ 요구 사항

• Node.js >= 24 — @trishchuk/fetch에 필요합니다.

• 사전 빌드된 네이티브 바이너리는 macOS (arm64, x64), Linux (x64/arm64, glibc 및 musl) 및 Windows (x64)용으로 제공됩니다. 다른 플랫폼은 기본 클라이언트에서 지원되지 않습니다.

📦 설치 및 설정

옵션 1: npx로 실행 (설치 불필요)

npx를 통해 서버를 직접 실행할 수 있습니다:

npx -y @trishchuk/mcp-fetch-server

옵션 2: 전역 또는 로컬 설치

# Global
npm install -g @trishchuk/mcp-fetch-server

# Or clone & install locally
git clone https://github.com/x51xxx/mcp-fetch-server.git
cd mcp-fetch-server
npm install

⚙️ MCP 클라이언트 설정

Claude Code

CLI를 통해 직접 추가:

# Using npx (recommended)
claude mcp add fetch -- npx -y @trishchuk/mcp-fetch-server

# Or using local path
claude mcp add fetch -- node /path/to/mcp-fetch-server/src/index.js

Claude Desktop

claude_desktop_config.json에 추가:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@trishchuk/mcp-fetch-server"]
    }
  }
}

Cursor / Windsurf / Antigravity (.mcp.json)

작업 공간에 .mcp.json을 생성하거나 업데이트:

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@trishchuk/mcp-fetch-server"]
    }
  }
}

🛠️ 도구 참조: fetch

입력 매개변수

응답 스키마

1. 성공적인 HTTP 교환

완료된 모든 HTTP 전송은 표준 JSON 결과를 반환합니다 (redirect: "manual" 아래의 404, 500 또는 3xx 포함):

{
  "status": 200,
  "statusText": "OK",
  "ok": true,
  "url": "https://example.com/data",
  "redirected": false,
  "headers": {
    "content-type": "application/json; charset=utf-8",
    "cache-control": "max-age=3600"
  },
  "bodyEncoding": "text",
  "body": "{\"message\": \"Hello world\"}",
  "truncated": false
}

2. 네트워크 / 전송 실패

네트워크 연결이 실패하거나 시간이 초과되거나 URL이 유효하지 않은 경우, 도구는 isError: true를 반환합니다:

{
  "error": true,
  "code": "TIMEOUT",
  "message": "failed to read response body: request or response body error: operation timed out"
}

💡 에이전트 사용 예시

1. 보호 대상의 봇 감지 우회

{
  "url": "https://protected-site.com/products",
  "impersonate": "chrome_147",
  "platform": "macos",
  "headers": {
    "Accept-Language": "en-US,en;q=0.9"
  }
}

2. 영구 세션(쿠키 저장소)을 사용한 다단계 스크래핑

// Step 1: Login / Obtain Session Cookie
{
  "url": "https://example.com/api/login",
  "method": "POST",
  "session": "agent-crawler-01",
  "headers": { "Content-Type": "application/json" },
  "body": "{\"user\":\"admin\",\"password\":\"secret\"}"
}

// Step 2: Access protected resource (session cookies automatically preserved)
{
  "url": "https://example.com/api/dashboard",
  "session": "agent-crawler-01"
}

3. SOCKS5 프록시를 통한 라우팅

{
  "url": "https://geo-restricted.example.com",
  "proxy": "socks5://user:pass@proxy.example.com:1080",
  "impersonate": "safari_26"
}

4. 바이너리 자산 가져오기 (이미지, PDF)

{
  "url": "https://example.com/report.pdf",
  "encoding": "base64"
}

5. SSRF 안전 수집을 위한 DNS 핀

{
  "url": "https://internal-origin.example.com/feed",
  "resolve": {
    "internal-origin.example.com": "192.0.2.42"
  },
  "redirect": "manual"
}

🔬 가장 프리셋 및 핑거프린트

@trishchuk/mcp-fetch-server는 광범위한 브라우저 핑거프린트를 지원합니다:

• Chrome: "chrome_100" … "chrome_149" (예: "chrome_147", "chrome_131", "chrome_116")

• Edge: "edge_101" … "edge_148"

• Opera: "opera_116" … "opera_131"

• Firefox: "firefox_109", "firefox_133", "firefox_147" …, "firefox_private_136" 및 "firefox_android_135" 포함

• Safari: "safari_15.3" … "safari_26.4", iOS/iPad 변형 포함 ("safari_ios_26", "safari_ipad_26")

• OkHttp (Android 앱): "okhttp_3.9" … "okhttp_5"

• 동적: "random", "weighted_random" (핑거프린트를 자동 순환, session별 고정)

버전 번호는 밑줄을 사용합니다 (chrome_147, chrome147 아님). 알 수 없는 이름은 모든 허용된 변형을 나열하는 InvalidArg 오류와 함께 빠르게 실패합니다.

🧪 개발

npm install
npm start          # run the server over stdio
npm test           # end-to-end smoke tests, no network required
npm run format     # format with Biome
npm run lint       # lint with Biome
npm run check      # format + lint check, also run before publish

테스트는 stdio를 통해 실제 서버를 실행하고 로컬 HTTP 서버에 대해 MCP 클라이언트로 구동하여 제한에서의 잘림, 리디렉션 모드, HEAD, base64 본문, 시간 초과 및 전송 오류를 다룹니다.

📄 라이선스

MIT © Taras Trishchuk