QuokkaPix MCP Runner

Local-first MCP adapter and cloud-to-local bridge for private QuokkaPix Image and Video workflows.

QuokkaPix MCP Runner lets AI agents process local images and videos by opening the matching QuokkaPix browser surface, applying an official recipe or direct settings, selecting local files through the browser input, saving the output, and writing a machine-readable result manifest. Image runs write quokkapix-result.json; Video runs write quokkapix-video-result.json.

It supports two compatible modes:

• local stdio for Image and Video in Claude Desktop, Cursor, LM Studio/Ollama wrappers and other local MCP clients;
• bridge for remote Image and Video MCP clients such as Claude web, while Chromium and all media processing remain on the user's computer.

Repository: https://github.com/quokkapix/quokkapix-mcp

npm package: https://www.npmjs.com/package/quokkapix-mcp

Glama listing: https://glama.ai/mcp/servers/quokkapix/quokkapix-mcp

mcpservers.org listing: https://mcpservers.org/servers/quokkapix/quokkapix-mcp

Browser compatibility matrix: https://quokkapix.com/en/browser-compatibility/

Browser benchmark: https://quokkapix.com/en/browser-image-processing-benchmark/

Video compatibility matrix: https://video.quokkapix.com/browser-compatibility/

Video benchmark: https://video.quokkapix.com/browser-video-processing-benchmark/

Quick start:

npx quokkapix-mcp

Cloud-to-local bridge:

npx quokkapix-mcp bridge --input-root ./media --output-root ./quokkapix-output

What This Is

This package is a local automation adapter around two browser surfaces:

https://quokkapix.com/#agent=1
https://video.quokkapix.com/#agent=1

The adapter uses Playwright to drive local Chromium. Image uses window.QuokkaPixAgent; Video uses window.QuokkaPixVideoAgent.

Image, video and audio files are processed in the user's browser runtime. Source media bytes are not uploaded to a QuokkaPix processing server. Local transcription may download and cache Whisper model files, but does not upload the selected media with that model request.

The optional bridge mode connects outward to the QuokkaPix control plane. The remote MCP endpoint relays tool settings, relative file names, status and result metadata. It has no media upload endpoint and does not relay source image, video, audio or output bytes.

What This Is Not

This package is not:

• a public server-side media processing API;
• a hosted media-processing service (the remote MCP control plane only coordinates a paired local bridge);
• a GPU/CPU media-processing backend run by QuokkaPix;
• a way to pass local file paths to quokkapix.com by URL;
• a replacement for browser memory limits.

Local file paths are available only to the local MCP runner on the user's machine. The public QuokkaPix website still receives files only through the browser file input or dropzone.

Why Use It

Use this adapter when an AI agent needs repeatable media workflows like:

• prepare product photos for Shopify, Amazon, or Google Merchant;
• validate marketplace and social image outputs against sourced rule profiles;
• compress images to WebP for a website;
• remove EXIF/GPS metadata;
• generate social media image packs;
• watermark a batch of images;
• generate favicon and app icon packs;
• run custom QuokkaPix settings without manually clicking the UI.
• cut, crop, resize, convert or compress one local video;
• extract, mute, mix or replace video audio with a local music file;
• generate TXT, SRT or VTT transcripts locally, or burn subtitles into MP4;
• prepare sourced YouTube, TikTok Ads and Meta Reels video profiles.

The main value is privacy and low infrastructure cost: the agent gets practical Image and Video workflow tools, while media processing remains local in the user's browser.

Architecture

AI agent / MCP client
        |
        | stdio MCP
        v
quokkapix-mcp
        |
        | Playwright
        v
local Chromium browser
        |
        | window.QuokkaPixAgent or window.QuokkaPixVideoAgent
        v
quokkapix.com or video.quokkapix.com
        |
        | local browser processing
        v
downloaded output + surface-specific result manifest

Remote clients use the same package in bridge mode:

Claude web / remote MCP client
        |
        | OAuth 2.1 + Streamable HTTP (commands and metadata only)
        v
QuokkaPix control plane
        |
        | outbound authenticated long poll
        v
quokkapix-mcp bridge on the user's computer
        |
        | Playwright
        v
local Chromium -> local output + quokkapix-result.json or quokkapix-video-result.json

Depending on the selected surface, the adapter saves:

• the generated image, ZIP, PDF, video, audio or transcript output;
• quokkapix-result.json or quokkapix-video-result.json;
• a qa object returned to the agent.

Requirements

• Node.js >=20
• npm
• Playwright Chromium
• internet access for loading QuokkaPix and browser-side dependencies/models when needed
• local file paths that the MCP process can read

Bridge mode additionally requires explicit input and output roots. Remote calls cannot read or write outside those roots.

Install dependencies:

npm install
npx playwright install chromium

Remote MCP And Bridge Setup

1. Start the existing package in bridge mode:

npx -y quokkapix-mcp bridge \
  --input-root /absolute/path/to/input \
  --output-root /absolute/path/to/output

2. Approve the one-time pairing URL printed by the command.
3. Add https://quokkapix.com/mcp as a custom remote MCP connector.
4. Complete OAuth authorization in the browser.

The bridge stores its random device credential in ~/.quokkapix/bridge.json with owner-only permissions where the operating system supports them. Use --pair to approve another browser session or --reset to revoke the old device authorization and create a new credential.

Remote processing paths are relative to --input-root and --output-root. The bridge rejects path traversal and does not return absolute local paths to the cloud client.

MCP Tools

list_recipes

Lists official QuokkaPix recipes.

Use first when the agent does not know which workflow to run.

get_recipe

Returns one recipe by id, including:

• applySettings;
• file limits;
• expected output;
• QA contract;
• payment requirement.

Input:

{
  "id": "shopify_product_pack"
}

validate_recipe

Validates a custom recipe object before processing.

This does not upload files and does not start processing.

list_rule_profiles

Lists sourced marketplace and social image rule profiles.

Use this when an agent needs facts for Amazon, Shopify, Google Merchant, Etsy, eBay, Walmart, TikTok Shop, Mercado Libre, Temu, Shopee, Instagram, YouTube, LinkedIn, X, Pinterest, Facebook or TikTok before choosing a workflow or checking an output.

Every profile declares:

• sourceType: official or secondary;
• sourceUrl;
• confidence;
• requirements and recommendations that were found from the named source.

The runner does not invent missing marketplace requirements. Temu, Mercado Libre, Shopee and some YouTube entries are marked as secondary or category/country-specific where official public specs were limited.

get_rule_profile

Returns one rule profile by id, for example:

{
  "id": "amazon.product.image"
}

Agents can pass the returned facts into their own planning, or call validate_result_manifest with ruleProfileId.

validate_result_manifest

Validates an existing quokkapix-result.json against a recipe or custom QA contract.

This is useful when an agent wants to inspect a previous run and decide whether the output is acceptable.

Optional input:

{
  "ruleProfileId": "amazon.product.image",
  "manifest": {}
}

When ruleProfileId is provided, the QA report includes sourced marketplace checks such as supported formats, dimensions, source type and URL. If the browser result manifest includes outputs[].pixelQa, the validator also evaluates supported pixel-level visual checks such as white background, subject centering, safe margins and transparent background.

Video tools

• list_video_recipes — list official Cut, Crop, Convert, Compress, Audio and Transcribe recipes.
• get_video_recipe — return one Video recipe and its expected QA.
• validate_video_recipe — validate a custom Video recipe without processing media.
• list_video_rule_profiles — list sourced YouTube, TikTok Ads and Meta Reels profiles.
• get_video_rule_profile — return one Video profile with its official source.
• validate_video_result_manifest — validate an existing quokkapix-video-result.json.
• process_video — process one local video with an official recipe.
• process_video_with_settings — process one local video with direct QuokkaPixVideoAgent settings.

Example:

{
  "recipeId": "tiktok_vertical",
  "inputFile": "/Users/me/video/source.mp4",
  "outputDir": "/Users/me/video/out"
}

Audio mix example:

{
  "settings": {
    "tool": "audio",
    "audio": { "mode": "mix", "volume": 100, "musicVolume": 35 }
  },
  "inputFile": "/Users/me/video/source.mp4",
  "musicFile": "/Users/me/audio/music.wav",
  "outputDir": "/Users/me/video/out"
}

Version 0.7.0 exposes the unified Image/Video payment quote and token flow through the OAuth-protected remote MCP and paired local bridge. Remote inputFile, optional musicFile and outputDir values are relative to the configured roots; their bytes never pass through the control plane. Paid Video bridge calls require 0.7.0 or newer.

process_images

Processes local image files through QuokkaPix using either: