@trishchuk/mcp-fetch-server

Un servidor de alto rendimiento del Model Context Protocol (MCP) que proporciona una herramienta fetch resistente a bots para agentes de IA (Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Antigravity, etc.).

Desarrollado por @trishchuk/fetch — un cliente HTTP nativo al estilo curl-impersonate que imita con precisión las huellas TLS (JA3/JA4, ClientHello) y HTTP/2 de navegadores reales.

🚀 ¿Por qué este servidor?

Los clientes HTTP estándar de Node.js/Undici son inmediatamente detectados y bloqueados por los sistemas modernos de protección contra bots (Cloudflare Turnstile / Under Attack Mode, DataDome, PerimeterX / HUMAN, Akamai, Kasada, AWS WAF).

Además, las herramientas estándar de recuperación de MCP a menudo fallan con cargas útiles grandes o saturan los contextos de tokens de los LLM.

@trishchuk/mcp-fetch-server resuelve ambos problemas:

1. Imitación realista de navegadores: Replica suites de cifrado exactas, extensiones TLS, orden ALPN y marcos de configuración HTTP/2 de navegadores modernos (Chrome, Safari, Firefox).

2. Truncamiento seguro para contextos de LLM: Transmite y limita los cuerpos de respuesta a 2MB (maxResponseBytes). Las páginas demasiado grandes se truncan limpiamente y se marcan con "truncated": true en lugar de fallar con errores.

3. Sesiones con estado: Mantiene cookies, estados de inicio de sesión y grupos de conexión a través de múltiples llamadas de herramientas del agente usando el parámetro session.

4. Codificación inteligente: Detecta automáticamente los tipos MIME y devuelve texto UTF-8 limpio para HTML/JSON/XML o Base64 para archivos binarios (imágenes, PDFs, documentos).

Related MCP server: smart-webfetch-mcp

✅ Requisitos

• Node.js >= 24 — requerido por @trishchuk/fetch.

• Los binarios nativos precompilados están disponibles para macOS (arm64, x64), Linux (x64/arm64, glibc y musl) y Windows (x64). Otras plataformas no son compatibles con el cliente subyacente.

📦 Instalación y configuración

Opción 1: Ejecutar con npx (sin necesidad de instalación)

Puedes ejecutar el servidor directamente a través de npx:

npx -y @trishchuk/mcp-fetch-server

Opción 2: Instalación global o local

# 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

⚙️ Configuración del cliente MCP

Claude Code

Añadir directamente a través de 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

Añadir a tu 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)

Crear o actualizar .mcp.json en tu espacio de trabajo:

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

🛠️ Referencia de la herramienta: fetch

Parámetros de entrada

Esquemas de respuesta

1. Intercambio HTTP exitoso

Cualquier transferencia HTTP completada devuelve un resultado JSON estándar (incluyendo 404, 500 o 3xx bajo redirect: "manual"):

{
  "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. Fallo de red / transporte

Si la conexión de red falla, se agota el tiempo de espera o la URL no es válida, la herramienta devuelve isError: true:

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

💡 Ejemplos de uso para agentes

1. Evasión de detección de bots en un objetivo protegido

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

2. Raspado de múltiples pasos con sesión persistente (contenedor de cookies)

// 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. Enrutar a través de un proxy SOCKS5

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

4. Obtención de activos binarios (imágenes, PDFs)

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

5. Fijación DNS para ingestión segura contra SSRF

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

🔬 Preajustes de imitación y huellas

@trishchuk/mcp-fetch-server admite una amplia gama de huellas de navegador:

• Chrome: "chrome_100" … "chrome_149" (p. ej. "chrome_147", "chrome_131", "chrome_116")

• Edge: "edge_101" … "edge_148"

• Opera: "opera_116" … "opera_131"

• Firefox: "firefox_109", "firefox_133", "firefox_147" …, además de "firefox_private_136" y "firefox_android_135"

• Safari: "safari_15.3" … "safari_26.4", más variantes para iOS/iPad ("safari_ios_26", "safari_ipad_26")

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

• Dinámico: "random", "weighted_random" (rota las huellas automáticamente, fijado por session)

Los números de versión usan guiones bajos (chrome_147, no chrome147). Un nombre desconocido falla rápidamente con un error InvalidArg que enumera todas las variantes aceptadas.

🧪 Desarrollo

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

Las pruebas inician el servidor real a través de stdio y lo manejan con un cliente MCP contra un servidor HTTP local, cubriendo el truncamiento en el límite, modos de redirección, HEAD, cuerpos base64, tiempos de espera y errores de transporte.

📄 Licencia

MIT © Taras Trishchuk