Servidor MCP

Usa la API de Thunderbit a través del Model Context Protocol — busca, scrapea y extrae desde cualquier host de IA compatible con MCP.

Un servidor Model Context Protocol (MCP) que integra Thunderbit para destilar páginas a Markdown, extraer campos estructurados de cualquier página con instrucciones en lenguaje natural y ejecutar trabajos por lotes de hasta 100 URLs a la vez. Open source en GitHub y distribuido en npm como @thunderbit/mcp-server.

Características

Destila cualquier URL a Markdown limpio y listo para LLM
Extrae datos estructurados con un mapa plano de nombre de campo → instrucción
Sugiere automáticamente campos extraíbles con suggest_fields
Ejecuta trabajos por lotes con hasta 100 URLs y estado basado en polling
Override de API key por llamada para agentes multi-tenant
Soporte self-hosted vía THUNDERBIT_API_BASE_URL

Instalación

Obtén tu API key desde app.thunderbit.com/console.

Ejecutar con npx

env THUNDERBIT_API_KEY=tb_YOUR_API_KEY npx -y @thunderbit/mcp-server

Instalación manual

npm install -g @thunderbit/mcp-server

Ejecutar en Cursor

Edita ~/.cursor/mcp.json:

{
  "mcpServers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY"
      }
    }
  }
}

Tras guardar, refresca la lista de servidores MCP en Cursor Settings → Features → MCP Servers. El Composer Agent usará Thunderbit cuando le preguntes por datos web.

Ejecutar en Windsurf

Añade esto a ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY"
      }
    }
  }
}

Ejecutar en VS Code

Para configuración compartida del workspace, crea .vscode/mcp.json:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "apiKey",
      "description": "Thunderbit API Key",
      "password": true
    }
  ],
  "servers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "${input:apiKey}"
      }
    }
  }
}

Para configuración global de usuario, pega el mismo bloque servers en User Settings (JSON) bajo una clave mcp.

Ejecutar en Claude Desktop

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY"
      }
    }
  }
}

Si ves spawn npx ENOENT, Node.js no está en el PATH del sistema. Instala Node.js LTS desde nodejs.org y reinicia Claude Desktop por completo. En Windows también puedes ejecutar where npx y usar la ruta absoluta (p. ej. C:\Program Files\nodejs\npx.cmd) como valor de command.

Ejecutar en Claude Code

claude mcp add thunderbit -e THUNDERBIT_API_KEY=tb_YOUR_API_KEY -- npx -y @thunderbit/mcp-server

Ejecutar en Cline

En el panel MCP Servers de Cline, haz clic en Add Server y usa:

{
  "command": "npx",
  "args": ["-y", "@thunderbit/mcp-server"],
  "env": {
    "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY"
  }
}

Configuración

Variables de entorno

Obligatorias

THUNDERBIT_API_KEY — tu API key (tb_ seguida de 32 caracteres hex). Obligatoria salvo que cada llamada a la herramienta pase su propio argumento apiKey.

Opcionales

THUNDERBIT_API_BASE_URL — apunta a un gateway self-hosted. Por defecto: https://openapi.thunderbit.com
THUNDERBIT_TIMEOUT_MS — timeout HTTP por llamada. Por defecto: 120000 (2 minutos). Súbelo cuando el polling de batch sea lento.

Ejemplos de configuración

Para la API en la nube con configuración por defecto:

export THUNDERBIT_API_KEY=tb_your_key

Para instancias self-hosted:

export THUNDERBIT_API_KEY=tb_your_key
export THUNDERBIT_API_BASE_URL=https://openapi.your-domain.com
export THUNDERBIT_TIMEOUT_MS=300000

Configuración personalizada con Claude Desktop

{
  "mcpServers": {
    "thunderbit": {
      "command": "npx",
      "args": ["-y", "@thunderbit/mcp-server"],
      "env": {
        "THUNDERBIT_API_KEY": "tb_YOUR_API_KEY",
        "THUNDERBIT_API_BASE_URL": "https://openapi.thunderbit.com",
        "THUNDERBIT_TIMEOUT_MS": "180000"
      }
    }
  }
}

Override de API key por llamada

Cada herramienta acepta un argumento opcional apiKey que sobreescribe THUNDERBIT_API_KEY. Útil cuando un MCP server da servicio a varios usuarios finales:

{
  "url": "https://example.com",
  "apiKey": "tb_customer_specific_key"
}

Herramientas disponibles

1. Distill Tool (`thunderbit_distill`)

Convierte cualquier página web en Markdown limpio y listo para LLM. Cuesta 1 credit por llamada.

{
  "name": "thunderbit_distill",
  "arguments": {
    "url": "https://example.com/article",
    "renderMode": "basic",
    "waitFor": 1000,
    "includeTags": ["article", "main"],
    "excludeTags": ["nav", "footer"],
    "countryCode": "US",
    "timeout": 30000
  }
}

Opciones del Distill Tool

url: URL de la página web a convertir (obligatorio)
renderMode: none | basic | full — controla la profundidad del renderizado JS
waitFor: tiempo de espera en ms tras la carga (0–10000) — súbelo en SPAs
includeTags: etiquetas HTML a incluir (p. ej. ["article", "main"])
excludeTags: etiquetas HTML a excluir (p. ej. ["nav", "footer"])
countryCode: código ISO de 2 letras en mayúsculas (por defecto: US)
timeout: timeout de petición en ms (5000–60000)
apiKey: sobrescribe la key de la variable de entorno para esta llamada

Mejor para: Lectura de artículos, ingesta para RAG, resumen masivo de páginas, análisis de contenido. Devuelve: String Markdown.

2. Extract Tool (`thunderbit_extract`)

Extrae datos estructurados de una página web. El schema es un mapa plano de fieldName → instrucción en lenguaje natural. Cuesta 20 credits por llamada.

Nota: la spec OpenAPI upstream describe schema como JSON Schema. El servidor en producción espera el mapa plano de instrucciones que se muestra debajo; estamos alineando la spec.

{
  "name": "thunderbit_extract",
  "arguments": {
    "url": "https://example.com/product",
    "schema": {
      "name": "product name",
      "price": "the listed price as a number",
      "currency": "3-letter currency code",
      "inStock": "true if the product is available, false otherwise"
    },
    "renderMode": "basic"
  }
}

El resultado data.data siempre es un array, incluso cuando solo esperas un único registro:

{
  "data": {
    "url": "https://example.com/product",
    "data": [
      { "name": "iPhone 15 Pro", "price": 999, "currency": "USD", "inStock": true }
    ]
  }
}

Opciones del Extract Tool

url: URL de la página web (obligatorio)
schema: Record<string, string> plano — nombre de campo → instrucción (obligatorio)
renderMode: none | basic | full
waitFor: tiempo de espera tras la carga en ms (0–10000)
timeout: timeout de petición en ms (5000–120000)
apiKey: override de key por llamada

Mejor para: Generación de leads, monitoreo de precios, análisis competitivo, construcción de datasets. Devuelve: array data.data de objetos cuyas claves son los nombres de campo de tu schema.

3. Suggest Fields Tool (`thunderbit_suggest_fields`)

Analiza una página y propone campos extraíbles. Úsala primero cuando no sepas qué datos contiene una página. Cuesta 1 credit por llamada.

{
  "name": "thunderbit_suggest_fields",
  "arguments": {
    "url": "https://example.com/product",
    "prompt": "Focus on pricing, availability, and shipping",
    "countryCode": "US"
  }
}

Opciones del Suggest Fields Tool

url: URL de la página web a analizar (obligatorio)
prompt: pista opcional para guiar a la IA
countryCode: código ISO de 2 letras (por defecto: US)
apiKey: override de key por llamada

Mejor para: Descubrir el schema antes de ejecutar extract; arrancar nuevos objetivos de scraping. Devuelve: Array de objetos { name, type, instruction }, listo para pasar a thunderbit_extract.

4. Batch Distill Create (`thunderbit_batch_distill_create`)

Envía hasta 100 URLs para destilación. Devuelve un job ID — haz polling con thunderbit_batch_distill_status hasta completar. Cuesta 1 credit por URL.

{
  "name": "thunderbit_batch_distill_create",
  "arguments": {
    "urls": [
      "https://example.com/page-1",
      "https://example.com/page-2",
      "https://example.com/page-3"
    ],
    "timeout": 30000
  }
}

Opciones de Batch Distill Create

urls: array de URLs (1–100, obligatorio)
timeout: timeout de petición por página en ms (5000–60000)
apiKey: override de key por llamada

Mejor para: Ingesta RAG masiva, destilación completa de un sitio cuando se combina con el endpoint Map. Devuelve: { id, status, total } — pasa id a la herramienta de status.

5. Batch Distill Status (`thunderbit_batch_distill_status`)

Hace polling de un trabajo de batch distill y recupera resultados paginados. Gratis.

{
  "name": "thunderbit_batch_distill_status",
  "arguments": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "page": 0,
    "pageSize": 20
  }
}

Opciones de Batch Distill Status

jobId: Job ID de thunderbit_batch_distill_create (obligatorio)
page: índice de página basado en 0 (por defecto 0)
pageSize: resultados por página, 1–100 (por defecto 20)
apiKey: override de key por llamada

Mejor para: Polling; recuperación final de resultados. Incrementa page hasta que results esté vacío. Devuelve: { id, status, total, completed, failed, creditsUsed, createdAt, completedAt, results: [{ index, url, success, markdown, error }, …] }. El status a nivel de job es el enum (PENDING / PROCESSING / COMPLETED / FAILED / CANCELLED); cada item de resultado por URL usa un campo booleano success, no status.

6. Batch Extract Create (`thunderbit_batch_extract_create`)

Envía hasta 100 URLs para extracción con un único schema compartido. Cuesta 20 credits por URL.

{
  "name": "thunderbit_batch_extract_create",
  "arguments": {
    "urls": [
      "https://example.com/product-1",
      "https://example.com/product-2"
    ],
    "schema": {
      "name": "product name",
      "price": "the listed price as a number"
    },
    "timeout": 60000
  }
}

Opciones de Batch Extract Create

urls: array de URLs (1–100, obligatorio)
schema: Record<string, string> plano (campo → instrucción) aplicado a cada URL (obligatorio)
timeout: timeout de petición por página en ms (5000–120000)
apiKey: override de key por llamada

Mejor para: Scraping de catálogos, construcción de datasets a gran escala. Devuelve: { id, status, total }.

7. Batch Extract Status (`thunderbit_batch_extract_status`)

Hace polling de un trabajo de batch extract. Gratis.

{
  "name": "thunderbit_batch_extract_status",
  "arguments": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "page": 0,
    "pageSize": 20
  }
}

Mismas opciones que thunderbit_batch_distill_status. Devuelve datos extraídos paginados por URL.

Flujo recomendado

thunderbit_suggest_fields — descubre qué datos expone la página
thunderbit_extract (o thunderbit_distill) — extrae una sola URL
thunderbit_batch_*_create — escala a hasta 100 URLs
thunderbit_batch_*_status — haz polling hasta el estado final

Manejo de errores

Cada herramienta devuelve los errores como errores de herramienta MCP (isError: true) con una pista estructurada, para que el modelo decida si reintenta o propaga el fallo al usuario.

// Pseudo-code: how the host receives an error
{
  isError: true,
  content: [{
    type: "text",
    text: "Thunderbit API error (402): INSUFFICIENT_CREDITS — Top up at https://thunderbit.com/billing"
  }]
}

HTTP	Code	Pista emitida por el servidor
401	`API_KEY_INVALID_FORMAT` / `API_KEY_NOT_FOUND`	"Check your API key at https://app.thunderbit.com/console"
402	`INSUFFICIENT_CREDITS`	"Top up at https://thunderbit.com/billing"
429	`RATE_LIMIT_EXCEEDED`	"Rate limit exceeded, retry later"
5xx	`INTERNAL_ERROR` / `DISTILL_FAILED`	(sin pista, mensaje del servidor pasado tal cual)

Lista completa de códigos: API Reference → Errors.

Solución de problemas

Las herramientas no aparecen en el host. Reinicia el host por completo tras editar la configuración. El servidor escribe una línea de arranque por stderr — revisa el archivo de logs MCP del host.

Cannot find module '@thunderbit/mcp-server'. Preinstala (npm install -g @thunderbit/mcp-server) o permite el acceso de red de npx desde el sandbox del host.

401 en la primera ejecución. El bloque env es por servidor — verifica que la key no esté atrapada en otra entrada de servidor. Prueba la ruta de instalación manual con la key exportada en la shell para aislar.

Los trabajos por lotes se quedan colgados. La herramienta MCP solo envía y hace polling; no mantiene una conexión de larga duración. Sube THUNDERBIT_TIMEOUT_MS a 180000+ para batches grandes, o combina batch_*_create con un webhook en tu aplicación para fire-and-forget.

CLI — las mismas operaciones, desde la shell
Quickstart — HTTP puro si prefieres no usar MCP
API Reference — detalles de los endpoints