quokkapix/quokkapix-mcp

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:
npm package:
Glama listing:
mcpservers.org listing:
Browser compatibility matrix:
Browser benchmark:
Video compatibility matrix:
Video benchmark:
Quick start:
Cloud-to-local bridge:
What This Is
This package is a local automation adapter around two browser surfaces:
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
Remote clients use the same package in bridge mode:
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:
Remote MCP And Bridge Setup
1. Start the existing package in bridge mode:
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.