just-every/mcp-screenshot-website-fast

Captura de pantalla de alta calidad optimizada para la API de Claude Vision. Divide automáticamente páginas completas en fragmentos de 1072x1072 píxeles (1,15 megapíxeles) con viewports configurables y estrategias de espera para contenido dinámico.

GitHub
110
Prueba este MCPPatrocinado

Documentación

@just-every/mcp-screenshot-website-fast

Captura de capturas de pantalla de páginas web rápida y eficiente, optimizada para herramientas de codificación CLI. Divide automáticamente páginas completas en fragmentos de 1072x1072 para un procesamiento óptimo.

Screenshot Website Fast MCP server

npm version GitHub Actions

Resumen

Diseñada específicamente para flujos de trabajo de visión por IA, esta herramienta captura capturas de pantalla de alta calidad con limitación automática de resolución y división en fragmentos para un procesamiento óptimo por la API de visión de Claude y otros modelos de IA. Garantiza que las capturas de pantalla tengan un tamaño perfecto de 1072x1072 píxeles (1.15 megapíxeles) para una compatibilidad máxima.

Características

  • 📸 Captura de pantalla rápida usando el navegador headless de Puppeteer
  • 🎯 Optimizada para Claude Vision con limitación automática de resolución (1072x1072 para 1.15 megapíxeles óptimos)
  • 🔲 División automática en fragmentos - Las páginas completas se dividen automáticamente en fragmentos de 1072x1072
  • 🎬 Captura de screencast - Graba series de capturas de pantalla a lo largo del tiempo con intervalos configurables
  • 🔄 Contenido siempre actualizado - Sin caché para garantizar capturas de pantalla actualizadas
  • 📱 Viewports configurables para pruebas responsivas
  • ⏱️ Estrategias de espera para contenido dinámico (networkidle, retrasos personalizados)
  • 📄 Captura de página completa por defecto para capturas de pantalla completas
  • 🎥 Exportación a WebP animado - Guarda screencasts como archivos WebP animados de alta calidad
  • 💉 Inyección de JavaScript - Ejecuta JS personalizado antes de la captura de screencast
  • 📦 Dependencias mínimas para instalaciones npm rápidas
  • 🔌 Integración MCP para flujos de trabajo de IA sin interrupciones
  • 🪟 Lanzador compatible con Windows para uso de MCP instalado con npm
  • 🔋 Eficiente en recursos - Limpieza automática del navegador después de 60 segundos de inactividad
  • 🧹 Gestión de memoria - Las páginas se cierran después de cada captura para evitar fugas

Instalación

Claude Code

claude mcp add screenshot-website-fast -s user -- npx -y @just-every/mcp-screenshot-website-fast

VS Code

code --add-mcp '{"name":"screenshot-website-fast","command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}'

Cursor

cursor://anysphere.cursor-deeplink/mcp/install?name=screenshot-website-fast&config=eyJzY3JlZW5zaG90LXdlYnNpdGUtZmFzdCI6eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBqdXN0LWV2ZXJ5L21jcC1zY3JlZW5zaG90LXdlYnNpdGUtZmFzdCJdfX0=

IDEs de JetBrains

Configuración → Herramientas → Asistente de IA → Model Context Protocol (MCP) → Agregar

Elige "Como JSON" y pega:

{"command":"npx","args":["-y","@just-every/mcp-screenshot-website-fast"]}

JSON sin procesar (funciona en cualquier cliente MCP)

{
  "mcpServers": {
    "screenshot-website-fast": {
      "command": "npx",
      "args": ["-y", "@just-every/mcp-screenshot-website-fast"]
    }
  }
}

Coloca esto en el mcp.json de tu cliente (por ejemplo, .vscode/mcp.json, ~/.cursor/mcp.json, o .mcp.json para Claude).

Requisitos previos

  • Node.js 20.x o superior
  • npm o npx
  • Chrome/Chromium (descargado automáticamente por Puppeteer)

Inicio rápido

Uso del servidor MCP

Una vez instalado en tu IDE, las siguientes herramientas están disponibles:

Herramientas disponibles

  • take_screenshot - Captura una captura de pantalla de alta calidad de una página web

    • Parámetros:
      • url (obligatorio): La URL HTTP/HTTPS a capturar
      • width (opcional): Ancho del viewport en píxeles (máx. 1072, predeterminado: 1072)
      • height (opcional): Alto del viewport en píxeles (máx. 1072, predeterminado: 1072)
      • fullPage (opcional): Capturar captura de pantalla de página completa con división en fragmentos (predeterminado: true)
      • waitUntil (opcional): Esperar hasta el evento: load, domcontentloaded, networkidle0, networkidle2 (predeterminado: domcontentloaded)
      • waitFor (opcional): Tiempo de espera adicional en milisegundos
      • directory (opcional): Directorio para guardar capturas de pantalla - devuelve rutas de archivo en lugar de imágenes base64

  • capture_selector - Captura una captura de pantalla de un elemento DOM específico que coincida con un selector CSS

    • Parámetros:
      • url (obligatorio): La URL HTTP/HTTPS a capturar
      • selector (obligatorio): Selector CSS para el elemento a capturar
      • width (opcional): Ancho del viewport en píxeles (máx. 1072, predeterminado: 1072)
      • height (opcional): Alto del viewport en píxeles (máx. 1072, predeterminado: 1072)
      • waitUntil (opcional): Esperar hasta el evento: load, domcontentloaded, networkidle0, networkidle2 (predeterminado: domcontentloaded)
      • waitForMS (opcional): Tiempo de espera adicional en milisegundos
      • selectorTimeoutMS (opcional): Cuánto tiempo esperar a que aparezca el selector antes de fallar (predeterminado: 5000)

Ejemplos de uso

Uso predeterminado (devuelve imágenes base64):

take_screenshot(url="https://example.com")

Guardar en directorio (devuelve rutas de archivo):

take_screenshot(url="https://example.com", directory="/path/to/screenshots")

Capturar un elemento específico:

capture_selector(url="https://example.com", selector="#main")

Al usar el parámetro directory:

  • Las capturas de pantalla se guardan como archivos PNG con marcas de tiempo
  • Se devuelven rutas de archivo en lugar de datos base64
  • Para capturas de pantalla divididas en fragmentos, cada fragmento se guarda como un archivo separado
  • El directorio se crea automáticamente si no existe

take_screencast

Captura una serie de capturas de pantalla a lo largo del tiempo para crear un screencast. Solo captura el fragmento superior (1072x1072) del viewport.

Parámetros

  • url (obligatorio): La URL a capturar
  • duration (opcional): Duración total en segundos (predeterminado: 10)
  • interval (opcional): Intervalo entre capturas de pantalla en segundos (predeterminado: 2)
  • jsEvaluate (opcional): Código JavaScript para ejecutar al inicio
  • waitUntil (opcional): Estrategia de espera: 'load', 'domcontentloaded', 'networkidle0', 'networkidle2'
  • waitForMS (opcional): Tiempo de espera adicional antes de comenzar
  • directory (opcional): Guardar como WebP animado en directorio (captura cada 1 segundo)

Ejemplos de uso

Screencast básico (5 fotogramas en 10 segundos):

take_screencast(url="https://example.com")

Tiempo personalizado:

take_screencast(url="https://example.com", duration=15, interval=3)

Con ejecución de JavaScript:

take_screencast(
  url="https://example.com",
  jsEvaluate="document.body.style.backgroundColor = 'red';"
)

Guardar como WebP animado:

take_screencast(url="https://example.com", directory="/path/to/output")

Al usar el parámetro directory:

  • Se crea un WebP animado con intervalos de 1 segundo
  • Los fotogramas individuales también se guardan como archivos PNG
  • La animación se repite para siempre por defecto
  • WebP proporciona una calidad excelente:
    • Soporte completo de color (sin limitación de 256 colores)
    • Compresión eficiente para animaciones web
    • Perfecto para fondos con degradados y animaciones suaves
    • Tamaños de archivo más pequeños en comparación con GIF con mejor calidad

Uso en desarrollo

Instalación

npm install
npm run build

Capturar captura de pantalla

# Full page with automatic tiling (default)
npm run dev capture https://example.com -o screenshot.png

# Viewport-only screenshot  
npm run dev capture https://example.com --no-full-page -o screenshot.png

# Wait for specific conditions
npm run dev capture https://example.com --wait-until networkidle0 --wait-for 2000 -o screenshot.png

Opciones de CLI

  • -w, --width <pixels> - Ancho del viewport (máx. 1072, predeterminado: 1072)
  • -h, --height <pixels> - Alto del viewport (máx. 1072, predeterminado: 1072)
  • --no-full-page - Deshabilitar captura de página completa y división en fragmentos
  • --wait-until <event> - Esperar hasta el evento: load, domcontentloaded, networkidle0, networkidle2
  • --wait-for <ms> - Tiempo de espera adicional en milisegundos
  • -o, --output <path> - Ruta del archivo de salida (obligatorio para salida dividida en fragmentos)

Función de reinicio automático

El servidor MCP incluye capacidad de reinicio automático por defecto para mayor fiabilidad:

  • Reinicia automáticamente el servidor si falla
  • Maneja excepciones no capturadas y rechazos de promesas
  • Implementa retroceso exponencial (máx. 10 intentos en 1 minuto)
  • Registra todos los intentos de reinicio para monitoreo
  • Maneja señales de apagado con elegancia (SIGINT, SIGTERM)

Para desarrollo/depuración sin reinicio automático:

# Run directly without restart wrapper
npm run serve:dev

Arquitectura

mcp-screenshot-website-fast/
├── src/
│   ├── internal/       # Core screenshot capture logic
│   ├── utils/          # Logger and utilities
│   ├── index.ts        # CLI entry point
│   ├── serve.ts        # MCP server entry point
│   └── serve-restart.ts # Auto-restart wrapper

Desarrollo

# Run in development mode
npm run dev capture https://example.com -o screenshot.png

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run typecheck

# Linting
npm run lint

¿Por qué esta herramienta?

Diseñada específicamente para flujos de trabajo de visión por IA:

  1. Optimizada para la API de visión de Claude - Limitación automática de resolución a 1072x1072 píxeles (1.15 megapíxeles)
  2. División automática en fragmentos - Páginas completas divididas en fragmentos perfectos para procesamiento de IA
  3. Siempre actualizada - Sin caché para garantizar que obtengas el contenido más reciente
  4. MCP nativo - Integración de primera clase con herramientas de desarrollo de IA
  5. API simple - Interfaz limpia y directa para capturar capturas de pantalla

Contribuciones

¡Las contribuciones son bienvenidas! Por favor:

  1. Haz un fork del repositorio
  2. Crea una rama de características
  3. Agrega pruebas para la nueva funcionalidad
  4. Envía una solicitud de extracción

Solución de problemas

Problemas con Puppeteer

  • Asegúrate de que Chrome/Chromium pueda descargarse
  • Verifica la configuración del firewall
  • Intenta configurar PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true y proporciona un ejecutable personalizado

Calidad de la captura de pantalla

  • Ajusta las dimensiones del viewport
  • Usa estrategias de espera apropiadas
  • Verifica si el sitio requiere autenticación

Errores de tiempo de espera

  • Aumenta el tiempo de espera con la bandera --wait-for
  • Usa diferentes estrategias de --wait-until
  • Verifica si el sitio es accesible

Licencia

MIT