Spicrawl

Servidor MCP de Spicrawl

El servidor MCP de Spicrawl es un servidor del Protocolo de Contexto de Modelos (MCP) que brinda a los agentes de IA en Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI y Codex capacidades de extracción web a Markdown, extracción de datos estructurados, capturas de pantalla, sesiones de navegador y extracción por lotes como herramientas nativas.

Documentación · Obtén una clave API · SDK de TypeScript · CLI · Complementos para agentes · Registro de cambios

Inicio rápido

1. Crea una clave API en app.spicrawl.com. Las claves comienzan con spicrawl_live_ o spicrawl_test_.

2. Conecta el endpoint alojado, https://mcp.spicrawl.com/mcp (MCP Streamable HTTP, nada que instalar):

   export SPICRAWL_API_KEY=spicrawl_live_...
   claude mcp add --transport http spicrawl https://mcp.spicrawl.com/mcp \
     --header "Authorization: Bearer $SPICRAWL_API_KEY"
   

   Codex: codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY

3. O ejecútalo localmente sobre stdio (Node.js 20+), para clientes que solo lanzan servidores locales:

   claude mcp add spicrawl --env SPICRAWL_API_KEY=$SPICRAWL_API_KEY -- npx -y @spicrawl/mcp
   

4. Pídele a tu agente: "Usa Spicrawl para leer https://example.com/pricing como markdown y lista cada plan con su precio." Llama a spicrawl_scrape y obtiene la página de vuelta como Markdown.

Ambos transportes sirven las mismas herramientas spicrawl_* (25 están definidas; el endpoint alojado lista 24 hasta que se lancen los navegadores remotos, consulta Herramientas), y cada llamada se ejecuta bajo tu clave con los mismos alcances, límites y créditos que una llamada directa a la API.

Qué hace

• Extrae cualquier URL a Markdown, texto, HTML, un sobre JSON o un PDF impreso con una sola herramienta, spicrawl_scrape. Markdown es el valor predeterminado y reduce la página a su contenido principal.
• Renderiza JavaScript con render: true (3 créditos). Una solicitud fetch simple cuesta 1 crédito, las capturas de pantalla, los PDF y actions usan un navegador completo (8 créditos), y mode: "auto" escala de fetch a navegador y cobra solo el nivel que funcionó (tabla de precios). Nunca eliges el renderizado tú mismo; Spicrawl elige el más económico que pueda hacer lo que la solicitud pide.
• Extrae datos estructurados con un mapa de selectores CSS/XPath (extract) o desde el JSON-LD, OpenGraph, Twitter Card y microdatos que una página publica (autoparse).
• Controla la página antes de la captura con 8 acciones de navegador tipadas: click, fill, wait_for, wait_for_navigation, scroll (incluido el desplazamiento infinito), select, evaluate y screenshot.
• Devuelve capturas de pantalla y PDF que el modelo puede ver: las capturas de pantalla llegan como bloques de imagen MCP (hasta 5 MB de base64 cada una) y las páginas impresas como bloques de recurso application/pdf (hasta 10 MB).
• Extrae por lotes miles de URLs como un solo trabajo asíncrono, hasta 10,000 elementos por llamada, con 9 herramientas para enviar, consultar, paginar resultados, reintentar, cancelar y mantener un trabajo abierto para rastreo.
• Mantén un navegador con sesión iniciada con sesiones persistentes: cookies, almacenamiento y un nivel de renderizado fijo reutilizado entre extracciones.
• Responde "¿cuánto costó eso?" desde las herramientas de uso y registro de solicitudes, y lee la documentación de Spicrawl desde dentro del agente.

Qué herramienta usar

• Si necesitas el contenido o los datos de una página ahora, usa spicrawl_scrape.
• Si la página está en blanco o es un esqueleto sin JavaScript, llama a spicrawl_scrape de nuevo con render: true.
• Si conoces la estructura de la página, usa extract con selectores CSS; si no la conoces, prueba autoparse.
• Si tienes más de unas 20 URLs, usa spicrawl_batch_submit, luego spicrawl_batch_status y spicrawl_batch_results.
• Si descubres URLs sobre la marcha (rastreo), envía con open: true, añade con spicrawl_batch_add_items y finaliza con spicrawl_batch_close.
• Si debes iniciar sesión primero, usa spicrawl_session_create y pasa su id como session_id a spicrawl_scrape.
• Si una llamada falló y necesitas saber por qué, usa spicrawl_request_get con el id de solicitud, o spicrawl_requests_list con only_errors.
• Si no estás seguro de un parámetro o un código de error, usa spicrawl_docs_search antes de adivinar.

Herramientas

25 herramientas, agrupadas por tarea. El endpoint alojado lista 24 hasta que se lancen los navegadores remotos: su tools/list sin clave y la tarjeta del servidor omiten spicrawl_browser_connect_url (Próximamente), mientras que una sesión abierta con tu clave y el paquete stdio (npx -y @spicrawl/mcp) lista las 25. Las herramientas rechazan argumentos desconocidos, por lo que un campo mal escrito falla con un error que lo nombra en lugar de descartarse silenciosamente. Cada herramienta establece un title y anotaciones explícitas de readOnlyHint, destructiveHint y openWorldHint, para que un cliente sepa qué llamadas confirmar: spicrawl_scrape no es de solo lectura (sus method y actions pueden enviar formularios), y spicrawl_batch_cancel, spicrawl_session_release y spicrawl_session_delete son destructivas. Cada herramienta también declara un outputSchema y devuelve structuredContent coincidentes junto al mismo texto que siempre devolvió, para que un cliente pueda leer campos (credits, status, next_cursor, ...) sin analizar texto. Los esquemas listan en qué puede confiar un agente y permanecen abiertos: los campos que la API añada más tarde pasan, y los estados y niveles son cadenas simples. Una herramienta que devuelve un documento o un arreglo JSON (spicrawl_docs_read, spicrawl_batch_task_content) lo coloca bajo content en structuredContent. Referencia completa de argumentos: docs.spicrawl.com/agents/mcp.

Extrae un sitio web a Markdown

Extrae por lotes muchas URLs

Sesiones de navegador

Uso e historial de solicitudes

Documentación

Próximamente

spicrawl_browser_connect_url acuñará una URL WebSocket CDP de un solo uso para controlar un navegador alojado por Spicrawl desde cualquier cliente CDP; los navegadores remotos aún no están disponibles. Es la herramienta número 25 y la única que el listado alojado sin clave y la tarjeta del servidor omiten (24 herramientas allí). Los esquemas también aceptan ai_extract, stealth, extract_preset, premium_proxy, proxy_country y sticky_key antes del lanzamiento. Los agentes no deberían enviarlas todavía. Para listar solo lo que funciona hoy, establece SPICRAWL_MCP_HIDE_UNAVAILABLE=1 (consulta Variables de entorno).

Ejemplos de indicaciones

• "Extrae https://example.com/pricing como markdown y resume los planes."
• "Obtén el nombre del producto, el precio y el estado de stock de esta URL." (spicrawl_scrape con extract o autoparse)
• "Toma una captura de pantalla de página completa de https://example.com después de que desaparezca el banner de cookies." (render, actions, screenshot_fullpage)
• "Extrae estas 500 URLs y dame el título de cada página." (spicrawl_batch_submit, luego spicrawl_batch_results)
• "¿Por qué falló mi última extracción?" (spicrawl_requests_list con only_errors, luego spicrawl_request_get)
• "¿Cuántos créditos he usado este mes?" (spicrawl_usage_summary)

Configura tu cliente MCP

Coloca tu clave en SPICRAWL_API_KEY y refiérela desde la configuración donde el cliente lo permita, para que la clave nunca termine en un archivo confirmado.

claude mcp add --transport http spicrawl https://mcp.spicrawl.com/mcp \
  --header "Authorization: Bearer $SPICRAWL_API_KEY"

{
  "mcpServers": {
    "spicrawl": {
      "type": "http",
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${SPICRAWL_API_KEY}" }
    }
  }
}

claude plugin marketplace add OfficialSpicrawl/agent-plugins
claude plugin install spicrawl@spicrawl-plugins

{
  "mcpServers": {
    "spicrawl": {
      "command": "npx",
      "args": ["-y", "@spicrawl/mcp"],
      "env": { "SPICRAWL_API_KEY": "spicrawl_live_..." }
    }
  }
}

{
  "mcpServers": {
    "spicrawl": {
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "spicrawl-api-key", "description": "Spicrawl API key", "password": true }
  ],
  "servers": {
    "spicrawl": {
      "type": "http",
      "url": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${input:spicrawl-api-key}" }
    }
  }
}

devin mcp add spicrawl https://mcp.spicrawl.com/mcp -H "Authorization: Bearer $SPICRAWL_API_KEY"

{
  "mcpServers": {
    "spicrawl": {
      "serverUrl": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer ${env:SPICRAWL_API_KEY}" }
    }
  }
}

export SPICRAWL_MCP_BEARER="$SPICRAWL_API_KEY"

{
  "mcpServers": {
    "spicrawl": {
      "httpUrl": "https://mcp.spicrawl.com/mcp",
      "headers": { "Authorization": "Bearer $SPICRAWL_MCP_BEARER" }
    }
  }
}

codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY

[mcp_servers.spicrawl]
url = "https://mcp.spicrawl.com/mcp"
bearer_token_env_var = "SPICRAWL_API_KEY"

[mcp_servers.spicrawl]
command = "npx"
args = ["-y", "@spicrawl/mcp"]
env = { SPICRAWL_API_KEY = "spicrawl_live_..." }

Variables de entorno

Sin variable de documentación definida, un servidor apuntado a una API autoalojada lee la documentación propia de esa API en <SPICRAWL_PUBLIC_BASE_URL or SPICRAWL_BASE_URL>/docs.

Autoalojar el servidor MCP sobre HTTP

El endpoint alojado ejecuta el servidor Streamable HTTP de este paquete. Para ejecutar el suyo propio:

SPICRAWL_MCP_ADDR=127.0.0.1:8090 \
SPICRAWL_BASE_URL=https://api.spicrawl.com \
npx -y @spicrawl/mcp --http

• SPICRAWL_BASE_URL por defecto es http://127.0.0.1:8080 en modo HTTP (una API de Spicrawl en el mismo host), no la API pública. Establézcala en https://api.spicrawl.com para servir la API pública.
• MCP se sirve en POST/GET/DELETE /mcp; liveness en GET /healthz (sin autenticación).
• GET /.well-known/mcp/server-card.json (sin autenticación, Cache-Control: public, max-age=3600) es una tarjeta de servidor estática para directorios como Smithery que no pueden escanear /mcp sin una clave: serverInfo, el transporte, la autenticación de portador y la lista de herramientas. Las herramientas se leen de las mismas definiciones que tools/list, como si SPICRAWL_MCP_HIDE_UNAVAILABLE estuviera activada: 24 herramientas, sin spicrawl_browser_connect_url. Una sesión abierta con una clave lista esa herramienta también, a menos que la variable esté definida.
• Sin ninguna clave, /mcp responde solo al descubrimiento: initialize, ping, la notificación initialized y tools/list (la misma lista de 24 herramientas que la tarjeta del servidor; no se emite Mcp-Session-Id y no se envía nada aguas arriba). Cualquier otra solicitud, incluida una tools/call, es 401, al igual que una solicitud que envía una clave mal formada o nombra una sesión. Un GET sin sesión es 405.
• Cada llamador envía su propia clave como Authorization: Bearer spicrawl_live_..., o, para una puerta de enlace que no puede enviar el prefijo Bearer , como un encabezado Authorization: spicrawl_live_..., x-api-key o api-key sin procesar (ver "Smithery y otras puertas de enlace" arriba; nunca un parámetro de consulta). La clave se verifica contra la API antes de abrir una sesión (401 si se rechaza, 503 con Retry-After si la API no se puede alcanzar), y una sesión se fija a la clave que la abrió.
• El servidor habla HTTP simple. Póngalo detrás de TLS antes de enviar claves a través de una red.

Endpoint de ChatGPT (OAuth)

El mismo proceso puede servir un segundo endpoint MCP restringido para aplicaciones de ChatGPT. Está apagado a menos que SPICRAWL_CHATGPT_ENABLED esté activada, y /mcp no cambia de ninguna manera.

La autenticación acepta solo tokens de acceso OAuth (spicrawl_oat_…):

• Sin token: 401 con WWW-Authenticate: Bearer resource_metadata="https://mcp.spicrawl.com/.well-known/oauth-protected-resource/chatgpt/mcp", scope="scrape batch".
• Un token malo, inactivo, caducado o de audiencia incorrecta, o una clave API (spicrawl_live_…/spicrawl_test_…, nunca aceptada aquí): el mismo 401 más error="invalid_token", error_description="…".
• Una llamada a una herramienta que los alcances del token no cubren: 403 con error="insufficient_scope". spicrawl_scrape necesita scrape, las herramientas por lotes necesitan batch, las herramientas de documentación necesitan solo un token válido.
• El servidor de autorización inalcanzable o que rechaza el secreto de este servidor: 503 con Retry-After.

Cada token se verifica con POST <issuer>/api/oauth/introspect (Authorization: Bearer <SPICRAWL_OAUTH_INTROSPECT_SECRET>, cuerpo de formulario token=…). Solo active: true con aud igual al recurso se acepta. Una respuesta positiva se almacena en caché por el SHA-256 del token durante como máximo 30 segundos y nunca más allá de su exp. Las herramientas se ejecutan aguas arriba bajo el api_key que devuelve la introspección; ni este ni el token se registran. Si la API rechaza esa clave a mitad de la llamada, la herramienta devuelve un error cuyo _meta["mcp/www_authenticate"] lleva un desafío invalid_token nuevo, y el token se elimina de la caché.

El endpoint lista seis herramientas, cada una con readOnlyHint/destructiveHint/openWorldHint explícitos, un título y securitySchemes: [{type: "oauth2", scopes: [...]}] (también en _meta.securitySchemes):

spicrawl_scrape es de solo lectura aquí, a diferencia de /mcp: este endpoint solo envía un GET, sin method, cuerpo, cabeceras ni actions. spicrawl_batch_submit no es de solo lectura, porque crea un trabajo.

spicrawl_batch_results rellena el contenido de un elemento que ha tenido éxito y que la página de resultados lista sin él, lo que ocurre mientras el trabajo aún está finalizando, desde GET /v1/batch/{id}/tasks/{seq}/content. Obtiene como máximo 25 elementos y 2 MiB por página. Un elemento que aún no se puede leer devuelve unavailable, y uno que supera el límite de tamaño omitted.

Cualquier otro argumento se rechaza, no se ignora. Los resultados conservan el contenido, el estado del sitio y los créditos cobrados; los identificadores de solicitud, las marcas de tiempo, los detalles del motor y del proxy, las referencias de almacenamiento y los identificadores de proyecto se omiten.

Instalado globalmente (npm install -g @spicrawl/mcp), el comando es spicrawl-mcp (alias spicrawl-mcp-server), con --http, --version y --help.

Preguntas frecuentes

¿Hay un servidor MCP de Spicrawl alojado?

Sí: https://mcp.spicrawl.com/mcp, MCP Streamable HTTP, autenticado con Authorization: Bearer <API key>, por lo que no hay nada que instalar.

¿Spicrawl es gratuito?

Spicrawl cobra créditos por cada solicitud exitosa, y durante la versión beta cada organización recibe un plan de 1,000 créditos al mes. Las solicitudes fallidas cuestan 0 créditos; un acierto de caché se factura al mismo precio que la recuperación que lo almacenó. Consulta Créditos.

¿Renderiza JavaScript?

Sí. Establece render: true en spicrawl_scrape para ejecutar la página en un navegador, o mode: "auto" para permitir que Spicrawl escale desde una recuperación simple solo cuando sea necesario. No hay argumento para elegir el renderizado en spicrawl_scrape ni en las herramientas por lotes: Spicrawl lo elige para cada solicitud y factura el nivel que la sirvió (fetch, js o browser, informado como engine en el resultado JSON).

¿Funciona con Claude Code, Cursor y VS Code?

Sí, y también con Claude Desktop, Windsurf, Gemini CLI, Codex y cualquier cliente que hable MCP Streamable HTTP con cabeceras personalizadas o que inicie servidores stdio.

¿Puede rastrear un sitio web completo?

No existe una herramienta única de rastreo. Extrae una página con links: true para obtener sus enlaces y luego envíalos a un trabajo por lotes abierto (open: true y spicrawl_batch_add_items).

¿Admite OAuth?

No en /mcp: solo acepta claves de API de Spicrawl, así que desactiva OAuth para ello en los clientes que lo intenten en un 401. El endpoint de ChatGPT separado en /chatgpt/mcp solo acepta tokens de acceso OAuth, cuando el operador lo activa.

¿Debo usar el servidor MCP, el SDK o la CLI?

Usa el servidor MCP cuando un agente de IA deba llamar a Spicrawl como herramientas. Usa @spicrawl/sdk en tu propio código TypeScript o JavaScript, @spicrawl/cli en una terminal o script de shell, y la API REST desde cualquier otro lenguaje.

Solución de problemas

curl -i https://mcp.spicrawl.com/mcp sin clave responde 401: el endpoint es accesible.

Paquetes relacionados

• @spicrawl/sdk: el SDK oficial de TypeScript para la API de Spicrawl.
• @spicrawl/cli: la interfaz de línea de comandos de Spicrawl.
• OfficialSpicrawl/agent-plugins: plugins que incluyen este servidor y la habilidad de Spicrawl para Claude Code, Codex, Cursor, Gemini CLI y más.

Enlaces

• Documentación: docs.spicrawl.com/agents/mcp
• Documentación para LLM: docs.spicrawl.com/llms.txt
• Panel y claves de API: app.spicrawl.com
• Problemas: github.com/OfficialSpicrawl/mcp/issues
• Seguridad: SECURITY.md. Nunca confirmes una clave de API; revoca una filtrada en app.spicrawl.com.

Publicación en el Registro MCP

server.json lista tanto el paquete npm/stdio como el endpoint alojado Streamable HTTP bajo io.github.OfficialSpicrawl/mcp. Las claves de API se solicitan a la persona que instala el servidor; ninguna clave pertenece al manifiesto.

El flujo de trabajo existente release publica en el Registro MCP después de que su trabajo npm tenga éxito, en envíos a main o ejecuciones manuales desde main. La autenticación del registro usa GitHub OIDC (id-token: write), por lo que no necesita ningún secreto nuevo, inicio de sesión de dispositivo ni registro DNS. El lanzamiento npm sigue usando el secreto existente NPM_TOKEN.

Para un lanzamiento, ejecuta npm version --no-git-tag-version X.Y.Z, actualiza el registro de cambios y envía los cambios a main. El hook de versión npm sincroniza ambas versiones en server.json. Si editas package.json manualmente, ejecuta npm run registry:sync. CI verifica el manifiesto contra su $schema oficial con Ajv y rechaza la deriva de nombre o versión antes de la publicación npm. Para ejecutar esa verificación localmente:

npm ci
npm run registry:validate
# Offline: pass a downloaded copy of the exact server.json $schema URL.
npm run registry:validate -- /path/to/server.schema.json

El trabajo del registro verifica que el paquete npm publicado tenga el mcpName coincidente antes de publicar. Una versión de registro existente se omite; los fallos de búsqueda detienen el trabajo. Para reintentar un fallo del registro o listar la versión npm actual ya publicada, ejecuta el flujo de trabajo release en main de nuevo. Usa una nueva versión para cambios de metadatos en un listado existente. El binario del publicador está fijado y su descarga se verifica contra las sumas de verificación del lanzamiento; actualiza su versión en release.yml al actualizar la CLI.

Verifica la publicación en https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.OfficialSpicrawl/mcp. El flujo de trabajo debe fusionarse en OfficialSpicrawl/mcp antes de que OIDC pueda publicar ese espacio de nombres. Las solicitudes de extracción de bifurcaciones validan y prueban, pero nunca ejecutan el trabajo del registro.

Referencias oficiales: inicio rápido de publicación, GitHub Actions, y servidores remotos.

Licencia

Apache-2.0