quokkapix-mcp
About
Local MCP adapter/server for QuokkaPix browser-only image workflows. It lets AI agents resize, compress, convert, remove backgrounds, strip metadata, watermark and export image packs locally through a browser without uploading source images to a processing server.
Details
- Author
- quokkapix
- Categories
- Design
Jump to
Setup
Install quokkapix-mcp in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/quokkapix/quokkapix-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
Local-first MCP adapter and cloud-to-local execution bridge for private QuokkaPix image workflows.
QuokkaPix MCP Runner lets AI agents process local image files with QuokkaPix by opening the QuokkaPix web app in a local browser, applying an official recipe or direct settings payload, uploading files through the browser file input, downloading the result, and writing a machine-readablequokkapix-result.json.
- localstdiofor Claude Desktop, Cursor, LM Studio/Ollama wrappers and other local MCP clients;
- bridgefor remote MCP clients such as Claude web, while Chromium and image 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/
npx quokkapix-mcp bridge --input-root ./images --output-root ./quokkapix-output
This package is a local automation adapter around the browser app at:
The adapter uses Playwright to drive a local Chromium browser. The browser runs the same QuokkaPix editor that humans use, including the in-browserwindow.QuokkaPixAgentAPI.
Image files are processed in the user's browser runtime. During normal processing, source image bytes are not uploaded to a QuokkaPix image-processing server.
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 does not expose an image upload endpoint and does not relay source or output image bytes.
- a public server-side image processing API;
- a hosted image-processing service (the remote MCP control plane only coordinates a paired local bridge);
- a GPU/CPU image-processing backend run by QuokkaPix;
- a way to pass local file paths toquokkapix.comby 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.
Use this adapter when an AI agent needs to run repeatable image 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.
The main value is privacy and low infrastructure cost: the agent gets a practical image workflow tool, while image processing remains local in the user's browser.
AI agent / MCP client | | stdio MCP v quokkapix-mcp | | Playwright v local Chromium browser | | window.QuokkaPixAgent + stable data-agent selectors v https://quokkapix.com/#agent=1 | | local browser processing v downloaded output + quokkapix-result.json
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
- the generated image, ZIP, or PDF output;
- quokkapix-result.json;
- aqaobject returned to the agent.
- 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.
npm install npx playwright install chromium
- Start the existing package in bridge mode:
npx -y quokkapix-mcp bridge \ --input-root /absolute/path/to/input \ --output-root /absolute/path/to/output
- Approve the one-time pairing URL printed by the command.
- Addhttps://quokkapix.com/mcpas a custom remote MCP connector.
- Complete OAuth authorization in the browser.
The bridge stores its random device credential in~/.quokkapix/bridge.jsonwith owner-only permissions where the operating system supports them. Use--pairto approve another browser session or--resetto revoke the old device authorization and create a new credential.
Remote processing paths are relative to--input-rootand--output-root. The bridge rejects path traversal and does not return absolute local paths to the cloud client.
Use first when the agent does not know which workflow to run.
- applySettings;
- file limits;
- expected output;
- QA contract;
- payment requirement.
{ "id": "shopify_product_pack" }
Validates a custom recipe object before processing.
This does not upload files and does not start processing.
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.
- sourceType:officialorsecondary;
- 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.
Returns one rule profile by id, for example:
{ "id": "amazon.product.image" }
Agents can pass the returned facts into their own planning, or callvalidate_result_manifestwithruleProfileId.
Validates an existingquokkapix-result.jsonagainst 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.
{ "ruleProfileId": "amazon.product.image", "manifest": {} }
WhenruleProfileIdis provided, the QA report includes sourced marketplace checks such as supported formats, dimensions, source type and URL. If the browser result manifest includesoutputs[].pixelQa, the validator also evaluates supported pixel-level visual checks such as white background, subject centering, safe margins and transparent background.
Processes local image files through QuokkaPix using either:
- an officialrecipeId;
- a full custom recipe object.
It opens a browser, applies the recipe, uploads files, starts processing, downloads the output, writesquokkapix-result.json, and returns QA results.
- watermarkLogoFile: local logo/image file uploaded into QuokkaPix's watermark logo input.
- backgroundImageFile: local image file uploaded into QuokkaPix's background replacement image input.
These assets are still uploaded only into the local browser page. They are not passed as URL paths to the public QuokkaPix website.
Processes local image files using a direct QuokkaPixapplySettingspayload.
Use this when the agent already knows the exact editor settings and does not want to wrap them in a recipe.
This is the broadest tool surface. It can drive the same settings surface as:
window.QuokkaPixAgent.applySettings(payload)
Supported editor areas depend on the QuokkaPix browser contract and include:
- resize;
- crop;
- rotate;
- convert;
- compress;
- advanced export to browser-supported formats and experimental JPEG XL when the browser-loaded encoder is available;
- metadata removal/reporting;
- PDF merge/split/extract tools throughtool=pdfandpdf.operationfor uploaded PDF files only; ZIP archives are accepted only for PDF merge and only PDF entries are extracted;
- background removal/replacement settings;
- watermark;
- effects;
- rename;
- constructor/scenario workflows.
For custom scenarios, prefer the explicit structured form:
{ "mode": "batch", "tool": "constructor", "steps": [ { "tool": "resize", "settings": { "mode": "fit", "width": 1200, "height": 1200 } }, { "tool": "watermark", "settings": { "type": "text", "text": "Brand", "layout": "tiled", "angle": -20 } }, { "tool": "compress", "settings": { "format": "webp", "quality": 0.82 } } ] }
Stepsettingsuse the same section keys aswindow.QuokkaPixAgent.applySettings.
PDF tools use PDF uploads instead of image uploads:
{ "tool": "pdf", "pdf": { "operation": "extract", "extractPages": "1,3-5", "extractOutput": "pdf" } }
Useoperation: "split"to export one uploaded PDF as a ZIP of one-page PDFs. Useoperation: "extract"withextractPagesto create one PDF containing only the selected pages from one uploaded PDF; page order is preserved, soextractPages: "3,1"exports page 3 before page 1. SetextractOutput: "zip"when the selected pages should be returned as separate one-page PDFs inside a ZIP.tool: "pdf"defaults to split. Split and extract are single-PDF workflows because page numbers refer to one source PDF. Useoperation: "merge"to combine multiple PDFs into one PDF in the current browser file order; merge is a batch workflow and switches the browser editor to batch mode. Human users can reorder merge files in the UI; MCP clients should pass files in the desired merge order.
ZIP upload is batch-only. If a user or agent selects a.zipin batch mode, QuokkaPix unpacks it locally in the browser and adds supported images from the archive to the batch queue. RAR and 7z are not accepted.
Fetches QuokkaPix agent payment policy and x402 endpoints.
Explains the current x402 payment flow for agents.
Important: this local MCP adapter does not sign x402 payments by itself. An x402-capable client or wallet must call the paid unlock endpoint and return anunlockToken.
Verifies a paid agent unlock token before processing.
Useconsume: falsefor preflight checks.
Only useconsume: trueif you intentionally want to consume the unlock immediately.
The hosted remote MCP endpoint also exposes:
- get_bridge_statusto check pairing and local availability;
- get_billing_statusto check whether a verified one-time unlock is staged;
- set_unlock_tokento stage an x402 unlock for the next paid local batch.
Remoteverify_unlock_tokenis preflight-only and never consumes the token. Actual consumption remains inside the local browser start path.
The runner loads recipes from the local project if present. If local recipe files are absent, it falls back to:
Agents should usually calllist_recipes, choose the closest recipe, then callprocess_images.
Useprocess_with_settingswhen the desired workflow is not covered by a recipe.
npm install npx playwright install chromium npm run check
npx quokkapix-runner --recipe website_webp_compress --input ./photo.jpg --output ./out
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
