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"
}

Remote MCP with local execution

Claude web and other cloud MCP clients can use the OAuth-protected remote endpoint while the npm adapter executes Image and Video operations on this computer.

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

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

The mcp:tools scope permits read tools. Processing and staged unlocks also require bridge:execute. The --reset option revokes the previous device before pairing a replacement.

The control plane relays settings, relative file names, status and result metadata. It has no media upload endpoint and does not relay source or output image, video or audio bytes.

Claude / Cursor / local MCP practical guide

Use this page when you want a desktop AI agent to process local image files with QuokkaPix. The MCP runner is a local stdio adapter: the MCP client starts quokkapix-mcp, the adapter opens QuokkaPix in a local browser, uploads files through the browser file input, applies a recipe or direct settings payload, downloads the result and writes quokkapix-result.json.

This is not a hosted image-processing API. Source images stay in the local browser workflow instead of being uploaded to a QuokkaPix processing server.

Windows fallback command

If a Windows MCP client cannot resolve npx directly, start it through cmd /c. Use this only when the simple npx command is not detected by the client.

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

Local MCP clients and LLM wrappers

Any MCP-compatible local client that can start a stdio server can use the same package. This includes desktop clients, editor agents, LM Studio or Ollama wrappers that expose MCP tools to a local model.

The important rule is the same everywhere: pass real local image file paths to the MCP tool call, not to the public website URL. QuokkaPix receives files only through the local browser file input opened by the runner.

First useful prompts

What to verify after the run

Free and paid agent runs

Image: 1-5 actual files are free, 6-25 cost 0.01 USDC, and 26-50 cost 0.02; PDF is free through 20 pages, then 0.01 through 50 and 0.02 through 300. A multi-step Image scenario costs 0.02. Video editing is free through 5 minutes, then 0.01 / 0.02 / 0.03; transcription is free through 5 minutes, then 0.02 / 0.04 / 0.06 through 45 minutes.

Upload first and obtain the exact local quote. Pay its product endpoint, then retry the unchanged run with unlockToken. The browser consumes it only immediately before processing; WebMCP and Bridge add no fee.

Troubleshooting

Security boundary

Use the official QuokkaPix URL or a trusted local development URL. Do not point the runner at an arbitrary third-party appUrl, because the adapter uploads local files into the browser page it opens. The public website does not receive local file paths, and the adapter does not turn QuokkaPix into a public server-side image API.

FAQ for agents and developers

What agents can do

• Run official recipes for Shopify, Amazon, Google Merchant, WebP compression, PDF export, metadata cleanup, social packs, avatar packs and watermark batches.
• Run direct custom settings with process_with_settings, using the same payload as window.QuokkaPixAgent.applySettings.
• Validate result manifests and get QA checks for formats, dimensions, size limits, output kind, required output names and ZIP contents.
• Read x402 payment options and verify unlock tokens for paid agent batch runs.
• Upload optional local asset files for logo watermarks and background-image replacement.
• Process one local video with Cut, Crop/Resize, Convert, Compress, Audio or Transcribe recipes and save quokkapix-video-result.json.

Current browser capabilities

• The optional capabilities.backends object reports planned processing, encoding and background-AI routes with explicit fallbacks. Existing MCP request and response fields are unchanged.
• Advanced export can use browser-loaded WASM encoders for JPEG, PNG optimization, WebP, AVIF and experimental JPEG XL when available.
• ZIP upload is batch-only: the browser unpacks supported images locally before the runner starts processing.
• PDF tools use tool=pdf in direct settings: split and extract use one uploaded PDF, merge uses a batch of PDFs, and images-to-PDF remains an image workflow. Extract preserves the page order from pdf-pages; use pdf-extract-output=zip for separate one-page PDFs.

What to check after a run

• Confirm that the output directory contains the generated image, ZIP or PDF plus quokkapix-result.json.
• Read qa.ok and qa.checks before accepting a marketplace or social-image batch.
• Keep source files separate because QuokkaPix writes delivery outputs, not replacement masters.
• For paid agent batches, fetch live payment options before requesting an x402 unlock token.

What makes a run acceptable

• The MCP client started the local stdio adapter and the adapter opened an expected QuokkaPix URL.
• Files entered through the browser file input, not through a public URL parameter.
• The manifest status is done, qa.ok is true when a recipe has QA, and warnings are reviewed before using the output.
• Upload first and obtain the exact local quote. Pay its product endpoint, then retry the unchanged run with unlockToken. The browser consumes it only immediately before processing; WebMCP and Bridge add no fee.

MCP tools

• 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

Official recipes

Examples

{
  "settings": {
    "mode": "single",
    "tool": "compress",
    "settings": {
      "compress": {
        "format": "webp",
        "quality": 0.82
      }
    }
  },
  "inputFiles": [
    "/Users/me/photo.jpg"
  ],
  "outputDir": "/Users/me/quokkapix-output"
}

Important notes

Images, videos and audio still enter through local browser inputs. QuokkaPix does not expose a public server-side media-processing API.