QuokkaPix MCP Runner

Image + Video local and remote MCP

Version 0.7.0 exposes one exact Image and Video quote/token flow through local stdio and the OAuth-protected remote MCP with a paired bridge. Use process_video with an official recipe or process_video_with_settings with direct settings. Video runs in local Chromium and never relays media bytes through the control plane.

{
  "recipeId": "tiktok_vertical",
  "inputFile": "/absolute/path/source.mp4",
  "outputDir": "/absolute/path/output"
}

MCP remoto con procesamiento local

Claude web y otros clientes MCP en la nube pueden conectarse mediante OAuth, mientras el adaptador npm existente ejecuta cada operación de imagen en el equipo del usuario.

npx quokkapix-mcp bridge --input-root /path/to/input --output-root /path/to/output

Remote MCP: https://quokkapix.com/mcp

El scope mcp:tools permite herramientas de lectura. El procesamiento y el almacenamiento de un unlock token también requieren bridge:execute. --reset revoca el dispositivo anterior antes de emparejar uno nuevo.

El control plane transmite ajustes, nombres de archivo relativos, estado y el result manifest. No tiene un endpoint de carga de imágenes ni transmite los bytes de origen o salida.

Guía práctica para Claude, Cursor y MCP local

Usa esta página cuando un agente de escritorio tenga que procesar imágenes locales con QuokkaPix. El MCP runner es un adaptador stdio local: el cliente MCP inicia quokkapix-mcp, el adaptador abre QuokkaPix en un navegador local, carga archivos mediante el selector del navegador, aplica una receta o ajustes directos, descarga el resultado y escribe quokkapix-result.json.

No es una API alojada de procesamiento de imágenes. Las imágenes originales permanecen en el flujo local del navegador y no se suben a un servidor de procesamiento de QuokkaPix.

Comando alternativo para Windows

Si un cliente MCP en Windows no resuelve npx directamente, ejecútalo mediante cmd /c. Úsalo solo cuando el comando npx simple no sea detectado por el cliente.

{
  "mcpServers": {
    "quokkapix": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "quokkapix-mcp"
      ],
      "env": {
        "QUOKKAPIX_APP_URL": "https://quokkapix.com/#agent=1"
      }
    }
  }
}

Clientes MCP locales y wrappers de LLM

Cualquier cliente MCP local que pueda iniciar un servidor stdio puede usar el mismo paquete. Esto incluye clientes de escritorio, agentes de editores y wrappers de LM Studio u Ollama que exponen herramientas MCP a un modelo local.

La regla importante es la misma en todos los casos: pasa rutas reales de archivos locales a la llamada MCP, no a la URL del sitio público. QuokkaPix recibe los archivos solo por el selector local del navegador que abre el runner.

Primeros prompts útiles

Qué verificar después de la ejecución

Ejecuciones gratuitas y de pago

Image: 1–5 archivos reales gratis, 6–25 cuestan 0,01 USDC y 26–50, 0,02; PDF es gratis hasta 20 páginas, luego 0,01 hasta 50 y 0,02 hasta 300. Un escenario Image de varios pasos cuesta 0,02. Video es gratis hasta 5 minutos y luego 0,01 / 0,02 / 0,03; la transcripción usa 0,02 / 0,04 / 0,06 hasta 45 minutos.

Carga primero y obtén la cotización local exacta. Paga el producto indicado y repite la misma ejecución con unlockToken. El navegador lo consume justo antes de procesar; WebMCP y Bridge no añaden cargos.

Solución de problemas

Límite de seguridad

Usa la URL oficial de QuokkaPix o una URL local de desarrollo confiable. No apuntes el runner a un appUrl arbitrario de terceros, porque el adaptador carga archivos locales en la página que abre. El sitio público no recibe rutas locales y el adaptador no convierte QuokkaPix en una API de procesamiento en servidor.

FAQ para agentes y desarrolladores

Qué pueden hacer los agentes

• Ejecutar recetas oficiales para Shopify, Amazon, Google Merchant, compresión WebP, exportación PDF, limpieza de metadatos, paquetes sociales, avatares y marcas de agua.
• Ejecutar custom settings directos con process_with_settings, usando el mismo payload que window.QuokkaPixAgent.applySettings.
• Validar result manifests y obtener QA de formato, dimensiones, límites de peso, tipo de salida, nombres requeridos y contenido ZIP.
• Leer condiciones de pago x402 y verificar tokens de desbloqueo para ejecuciones por lote de agentes.
• Subir archivos asset locales para marcas de agua con logotipo y fondos de reemplazo.

Capacidades actuales del navegador

• El objeto opcional capabilities.backends informa las rutas previstas de procesamiento, codificación e IA de fondo con fallbacks explícitos. Los campos MCP existentes no cambian.
• La exportación avanzada puede usar codificadores WASM para JPEG, optimización PNG, WebP, AVIF y JPEG XL experimental cuando están disponibles.
• La subida ZIP funciona solo en lote: el navegador descomprime localmente las imágenes compatibles antes de procesarlas.
• Las herramientas PDF se controlan con ajustes directos: split y extract usan un solo PDF, merge usa un lote de PDF e images-to-PDF sigue siendo un flujo para imágenes. Extract conserva el orden de pdf-pages; usa pdf-extract-output=zip para PDF separados por página.

Qué revisar después de una ejecución

• Confirma que la carpeta de salida contiene la imagen, ZIP o PDF generado y quokkapix-result.json.
• Lee qa.ok y qa.checks antes de aceptar un lote para marketplace o red social.
• Mantén los archivos fuente separados porque QuokkaPix crea copias de entrega, no reemplaza originales.
• Para lotes de agente de pago, consulta las opciones de pago actuales antes de pedir un token x402.

Cuándo una ejecución es aceptable

• El cliente MCP inició el adaptador stdio local y el adaptador abrió una URL esperada de QuokkaPix.
• Los archivos entraron por el selector de archivos del navegador, no por un parámetro de URL pública.
• El manifiesto tiene status done, qa.ok es verdadero cuando la receta tiene QA y las warnings se revisan antes de usar la salida.
• Carga primero y obtén la cotización local exacta. Paga el producto indicado y repite la misma ejecución con unlockToken. El navegador lo consume justo antes de procesar; WebMCP y Bridge no añaden cargos.

Herramientas MCP

• list_recipes
• get_recipe
• validate_recipe
• list_rule_profiles
• get_rule_profile
• validate_result_manifest
• process_images
• process_with_settings
• list_video_recipes
• get_video_recipe
• validate_video_recipe
• list_video_rule_profiles
• get_video_rule_profile
• validate_video_result_manifest
• process_video
• process_video_with_settings
• get_payment_options
• explain_payment_flow
• verify_unlock_token

Recetas oficiales

Ejemplos

{
  "recipeId": "shopify_product_pack",
  "inputFiles": [
    "/Users/me/photo.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output"
}

Notas importantes

Los archivos siguen entrando solo por el selector de archivos local del navegador. QuokkaPix no ofrece una API pública de procesamiento en servidor.