mini-creative-toolkit
The server exposes 8 MCP tools: one hosted text-to-image generator and seven local image/video processing operations.
Generate an image from a text prompt via Pollinations.ai (network required).
Upscale an image with Real-ESRGAN (requires discrete GPU; slow on integrated graphics).
Remove an image's background locally with rembg/ONNX (CPU-only, first-run model download).
Resize an image with Lanczos resampling, optionally preserving aspect ratio.
Convert images between PNG, JPEG, and WebP (flattens transparency for JPEG).
Extract a single video frame as a PNG thumbnail.
Convert a video clip to an optimized GIF (two-pass palette).
Trim a video losslessly by start time and duration.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mini-creative-toolkit Remove the background from this product photo and save as PNG."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Local media tools for MCP clients and the shell: strip GPS from a photo, resize, convert, cut out a background, trim a video. 22 of the 23 tools run on your CPU, and every reply states its own execution and network.
uvx --from git+https://github.com/Furkiozknn/mini-creative-toolkit mct inspect photo.jpgYour files stay on the machine: the one hosted tool (generate_image_free) is labelled network: required, and remove_background downloads a model's weights once (first-run-only), as does batch_process when it runs remove_background. The server puts network: none in the payload on 20 of its 23 tools. No clone, no API key, no GPU. Needs uv; ffmpeg only for video and audio. Measured on Windows 11: 21 s from an empty cache to the first result, 3 s once cached (docs/DENETIM.md).
Use it from Claude Code or any MCP client with one line:
claude mcp add --transport stdio mini-creative-toolkit -- uvx --from git+https://github.com/Furkiozknn/mini-creative-toolkit mct serve
Real commands, real output: the full record is docs/demo/komutlar.txt. photo.jpg is a synthetic picture with EXIF and GPS tags, not anybody's photo. The last command is an MCP client session over stdio (scripts/mcp_probe.py). Regenerate everything with uv run python scripts/demo-uret.py.
Use it when | Do not use it when |
You want resize, convert, strip-metadata, thumbnail, GIF, trim or compress done locally, and want each reply to state that nothing left the machine | You need generative editing or inpainting. The one generative tool, |
You give an agent file access and want every tool to declare what it needs ( | You need Real-ESRGAN quality without a discrete GPU. |
You have a folder of images: | You expect a sandbox. It runs with your permissions; set |
You want the answer to "what can this machine run?" before a job ( | You need a platform-certified preset. The built-in sizes are conveniences |
Contents
Related MCP server: media-mcp
Why this exists
Removing a background, fitting an image to 1080×1080, converting a folder to WebP, pulling three seconds out of a clip as a GIF, stripping GPS coordinates before you share a photo — none of this needs a model, and none of it needs somebody else's paid API. It is mechanical work, and it finishes on a laptop CPU in about the time it takes to read this sentence.
The interesting property of this project is not that it uses AI. It is how little of it needs to.
Of 23 tools, 22 run entirely on this machine. One — generate_image_free
— genuinely generates an image, so it genuinely has to call a hosted service,
and it says so in its own tool description, in its result payload, in the
capability matrix below, and in SECURITY.md. That tool lives alone in one
file, and a test asserts that no other module imports an HTTP client.
There is no global "CPU-only, no network" claim anywhere in this project, because two of its tools would make such a claim false. Requirements are declared per tool, in one table, from which both the MCP descriptions and the matrix below are generated.
What it does
Give an MCP client something like:
"Remove the background from this, make it 1080×1080 without cropping the subject, strip the metadata, and optimise it for the web."
and it has a tool for each step. Or ask it to inspect something first —
inspect_media reports what a file actually is rather than what its
extension claims — and decide from there.
Discovery
Tool | Does |
| Every tool's requirements and whether this machine can currently run it |
| Format, dimensions, codecs, duration, fps, metadata presence |
| rembg models with size, speed, and licence status |
| Built-in dimension presets |
Images
Tool | Does |
| Lanczos resize; fits inside the box without distorting by default |
| PNG / JPEG / WebP / AVIF, with quality and lossless controls |
| Rebuilds from raw pixels — EXIF, GPS, ICC, XMP, PNG text chunks all gone |
| Semi-transparent text at a corner or the centre |
| Subject cut-out to a transparent PNG |
| Tile many images into one review sheet |
| Byte equality, dimensions, and a coarse similarity score |
Upscaling
Tool | Does |
| FSRCNN — a real super-resolution CNN, CPU: 0.04 s for a 128×96 icon at 4×, about 3 s for a 1600×1200 photo at 2× |
| Real-ESRGAN via Upscayl — best quality, needs a discrete GPU |
| Picks between them and explains which and why |
Video and audio
Tool | Does |
| One frame as a PNG |
| Two-pass palette GIF, with frame-count guards |
| Lossless stream copy, re-encoding only when the copy lands short |
| Scale, always to even dimensions (H.264 requires them) |
| H.264/AAC at a chosen CRF |
| mp3 or wav |
Higher-level
Tool | Does |
| Inspect → choose a pipeline → apply → report every trade made |
| One operation over many files, bounded concurrency, failure isolated |
Hosted — the one that leaves your machine
Tool | Does |
| Text → image via Pollinations.ai. Your prompt is sent to a third party. |
Capability matrix
Generated from the same table the MCP tool descriptions use — run
mct capabilities for the live version, including what this machine is
actually missing.
Tool | Local | Network | GPU | External binary | Deterministic |
| yes | no | no | no | yes |
| yes | no | no | no | yes |
| yes | no | no | no | yes |
| yes | no | no | no | yes |
| yes | no | no | no | yes |
| yes | no | no | no | yes |
| yes | first run only | optional | no | per model |
| yes | no | no | no | yes |
| yes | no | required |
| yes |
| yes | no | optional | only if selected | yes |
| yes | no | no |
| yes |
| yes | no | no |
| yes |
| yes | no | no |
| yes |
| yes | no | no |
| yes |
| yes | no | no |
| yes |
| yes | no | no |
| yes |
| yes | no | no |
| yes |
| yes | no | no |
| yes |
| yes | first run only ( | no | per operation | yes |
| yes | no | no | no | yes |
| yes | no | no | no | yes |
| yes | no | no | no | yes |
| no | required | no | no | no |
"first run only" is not a hedge: rembg downloads a model's ONNX weights the
first time that model is used, then never again. batch_process inherits that
only when its operation is remove_background; its payload reports the
network need of the operation it actually ran. "per model" means
remove_background is reproducible for a given model but different models
give different cut-outs.
mct capabilities distinguishes two kinds of unmet requirement, because
conflating them sends you looking for a problem you do not have:
blockers — the tool cannot run at all.
video_thumbnailwithout ffmpeg.limitations — the tool runs, on fewer inputs.
inspect_mediawithout ffprobe still describes every image; it just cannot open a video.
The same table drives each tool's MCP behaviour hints and title, so a client can decide what needs a confirmation prompt:
readOnlyHint: the tool writes no file.destructiveHint: true exactly when the tool takesoverwrite, because then a caller can ask it to replace an existing file.batch_processhas no such parameter and only creates new, never-colliding files, so it is false.idempotentHint: true for the read-only tools only. A writer called withoutoutput_pathwrites a fresh file each time.openWorldHint: the network column above is not "no".
Inline previews. When a tool writes an image, the MCP reply carries:
the same JSON text and
structuredContentas before;a thumbnail as MCP image content: at most 512 px on the long side, PNG when the image has transparency, JPEG otherwise, first frame of a GIF;
a
resource_linkto the full-size file.
A client, and the model, can check a resize, a cut-out or a watermark without
opening a file on the server's disk. The thumbnail is a re-encoded copy, so the
output file is never touched, and an image that cannot be previewed simply gets
no preview. MCT_INLINE_PREVIEWS=0 switches previews off. The CLI and direct
Python calls are unchanged.
Install
Nothing to install for a first try, see the top. To keep mct on your PATH:
uv tool install git+https://github.com/Furkiozknn/mini-creative-toolkit
mct --versionTo work on the code, from a checkout:
git clone https://github.com/Furkiozknn/mini-creative-toolkit
cd mini-creative-toolkit
uv sync
uv run mct capabilitiesThat installs the package and its five dependencies. The FSRCNN weights (~120 KB total) ship inside the package — nothing to download.
ffmpeg and ffprobe must be on your PATH for every video and audio tool,
and for inspect_media on non-image files:
sudo apt-get install ffmpeg # Debian/Ubuntu
brew install ffmpeg # macOSOn Windows any ffmpeg build on PATH works (the WinGet package does).
Everything else works without them. mct capabilities will tell you exactly
which tools are blocked and why.
Optional: Real-ESRGAN upscaling
upscale_image reuses a local Upscayl
install. Nothing is bundled and nothing is downloaded — point two environment
variables at your own copy:
export UPSCAYL_BIN_PATH=/path/to/upscayl/resources/linux/bin/upscayl-bin
export UPSCAYL_MODELS_PATH=/path/to/upscayl/resources/modelsIf they are unset or wrong, upscale_image raises a clear error naming both
variables — and every other tool keeps working. Skip this entirely and use
upscale_image_fast, which needs no setup at all.
Register as an MCP server
claude mcp add --transport stdio mini-creative-toolkit -- uvx --from git+https://github.com/Furkiozknn/mini-creative-toolkit mct serveFrom a checkout instead, point Claude Code at the console script with an absolute project path:
claude mcp add --transport stdio mini-creative-toolkit -- \
uv run --project /absolute/path/to/mini-creative-toolkit mini-creative-toolkitOlder instructions said uv run --project /path/to/repo toolkit.py. uv
resolves toolkit.py against the current directory, not the project, so that
form only connects when Claude Code is started inside the repository; replace
it with the command above, or give toolkit.py as an absolute path. Other ways
to start the same server:
mct serve
python -m mini_creative_toolkit
mini-creative-toolkit # the console script server.json points uvx atTo see what a client sees without a client, uv run python scripts/mcp_probe.py photo.jpg
starts the server over stdio, sends initialize, tools/list and three real
tools/call requests, and checks every tool description for invisible
characters.
CLI
The CLI calls the same functions the MCP server does — there is no second implementation of any rule.
mct inspect photo.jpg
mct resize photo.jpg --width 1080 --height 1080
mct convert photo.png --format webp --quality 85
mct optimize photo.png --goal web
mct optimize photo.png --goal social --preset square
mct strip-metadata photo.jpg
mct watermark photo.jpg --text "© 2026" --position bottom-right --opacity 0.4
mct remove-bg photo.jpg
mct upscale icon.png --scale 4 # picks a method and explains it
mct thumbnail clip.mp4 --at 00:00:05
mct gif clip.mp4 --start 00:00:02 --duration 3 --fps 12 --width 480
mct trim clip.mp4 --start 00:00:10 --duration 15
mct compress clip.mp4 --crf 26
mct audio clip.mp4 --format mp3
mct contact-sheet renders/*.png --columns 4
mct compare a.png b.png
mct capabilities
mct presets
mct modelsAdd --json for machine-readable output, --log-level verbose to see the
underlying ffmpeg log when something fails, -o PATH to choose a destination
(--overwrite to allow replacing an existing file).
Exit codes: 0 success, 1 operation failed, 2 usage error.
Wildcards work on every shell: cmd.exe and PowerShell do not expand *.jpg, so mct batch
and mct contact-sheet do it themselves (only when no file of that literal name exists).
mct batch takes no -o: one path cannot hold many results, use --output-dir.
Batch processing
mct batch photos/*.jpg --operation optimize --options '{"goal":"web"}'
mct batch renders/*.png --operation resize --options '{"width":1080,"height":1080}'or as an MCP call:
{
"paths": ["a.png", "b.png", "c.png"],
"operation": "convert_format",
"options": {"target_format": "webp", "quality": 85}
}returning
{"total": 3, "succeeded": 2, "failed": 1, "results": [...], "errors": [...]}Three properties are enforced, not hoped for:
One bad file never loses the batch. Each item runs in its own try/except; failures land in
errorswith their original index.Concurrency is bounded and conservative. CPU-heavy operations (
remove_background,upscale_fast) get a lower cap than cheap ones — saturating every core with ONNX sessions makes a batch of 20 slower than doing them one at a time.Outputs cannot collide. Generated names carry random bytes as well as a timestamp, and passing an explicit
output_pathto a batch is refused rather than silently ignored.
Configuration
Nothing is required. Every variable exists to tighten a default or raise a limit your real workload legitimately exceeds.
Variable | Default | Meaning |
|
| Where generated files land |
| (unset) | Restrict file access to these directories |
| 512 | Largest input file |
| 1024 | Largest output file |
| 80000000 | Largest image read (decompression-bomb guard) or produced (resize, upscale, contact sheet) |
| 3600 | Longest video, in seconds |
| 7680 | Largest video dimensions |
| 200 | Largest batch |
| 4 | Workers for standard operations |
| 2 | Workers for CPU-heavy operations |
| 60 | Hosted call timeout, in seconds |
| 64 | Largest hosted response |
| 900 | ffmpeg / Upscayl timeout, in seconds |
|
|
|
|
| Return a bare path string, as before 2.0 |
|
| Keep rembg sessions and FSRCNN networks in memory between calls; |
|
| Attach a 512 px preview to image results; |
| — | Override a preset, e.g. |
| (unset) | Skip discrete-GPU detection (which only decides what |
| (unset) | Local Upscayl install |
A bad value fails loudly at startup with a message naming the variable, and every resource-limit error names the limit it hit.
Supported formats
Images, read: everything Pillow reads.
Images, written: PNG, JPEG, WebP, and AVIF if your Pillow build has it —
support is probed at runtime rather than assumed, because AVIF depends on how
Pillow was compiled. mct capabilities reports what this install can write.
Video and audio: whatever your ffmpeg build handles. video_resize and
video_compress output H.264/AAC in MP4; extract_audio writes mp3 or wav.
Security model
Full detail in SECURITY.md. The short version:
This project is a local media-processing tool, not a sandbox.
It runs as your user with your user's permissions, and MCP does not change that. What it does guarantee:
No
shell=Trueanywhere. A test parses the AST of every module to enforce it. Commands are argument lists; binaries come fromshutil.which.Every non-path value that reaches
argvis shape-constrained. Timestamps must match a digits-and-colons grammar much narrower than ffmpeg's own, so a value like-ssor-icannot be read as an option. Rejected, never sanitised.Paths are resolved before they are checked.
resolve()collapses..and follows symlinks first, so neither traversal nor a planted symlink can escape a configured allowed root.Nothing overwrites an existing file unless you say so. Writes are staged to a temporary sibling and committed only on success, so a crashed ffmpeg leaves no truncated file and no orphaned GIF palette; without
overwrite=truethe commit refuses a name that already exists, even one that appeared mid-run. Your input is replaced only if you name it asoutput_pathand passoverwrite=true.Dependencies stay quiet too. onnxruntime (under rembg) ships with telemetry on; the package sets
ORT_DISABLE_TELEMETRY=1before it can load, so thenetwork: nonein a payload also covers what a dependency would have sent.Sizes are bounded both ways.
MCT_MAX_IMAGE_PIXELSapplies to images read and to the image a resize, upscale or contact sheet would create.The hosted response is never trusted. Status, content type, a streaming byte budget, and an actual decode — an HTML error page served with HTTP 200 is refused rather than written out as a
.jpg.
If you are exposing this to a model you do not fully trust, set
MCT_ALLOWED_ROOTS. It is unset by default, and SECURITY.md says so
plainly rather than implying an isolation that does not exist.
Architecture
src/mini_creative_toolkit/
├── config.py MCT_* settings, limits, allowed roots
├── errors.py domain errors; MCP-facing message vs verbose detail
├── validation.py everything that reaches an argv entry passes through here
├── paths.py untrusted-path resolution + staged output manager
├── capabilities.py one table: requirements, readiness, description footers
├── media_info.py the engine behind inspect_media
├── results.py structured result shape
├── log.py stderr, three levels, never logs secrets or prompts
├── engines/ ffmpeg · images (Pillow+OpenCV) · background · upscayl · pollinations
├── tools/ the business rules — MCP and CLI both call these
├── server.py MCP registration and descriptions, no logic
├── cli.py mct — same functions, different surface
└── models/ bundled FSRCNN weightsTwo rules hold the shape:
Business logic exists once.
server.pyandcli.pyboth calltools/. A validation fix lands in both surfaces at the same moment.Capabilities are declared once. Tool descriptions, the readiness report, and the matrix above all read the same table, so a description cannot drift away from what the tool actually needs.
Testing
uv run pytest405 tests: 405 passed on Linux (Python 3.11, 3.12 and 3.13 in CI, 2026-10-19); before the 2.1.0 fixes, 342 of 347 passed and 5 were skipped on Windows 11 (Python 3.14, 45 s), and CI runs a Windows job too. The skips are file names and paths that only exist on POSIX.
Real files, real ffmpeg, real encoders — no mocked image libraries. The
exception is the hosted generator, which is tested entirely against an
httpx.MockTransport: CI never contacts Pollinations.ai, and a test suite
that quietly started making outbound requests would contradict the project's
central claim.
The suite covers unit tests for validation, path handling and configuration;
end-to-end image and video tests; security tests for traversal, symlink
escapes, shell metacharacters, unicode and awkward filenames, FIFOs, NUL
bytes, over-long paths and every resource limit; failure-mode tests for the
hosted engine (timeout, 4xx, 5xx, wrong content type, corrupt body, oversized
response); batch failure isolation; a real MCP stdio handshake; and static
checks over the repository itself — no shell=True, no developer-specific
paths, no outbound URL outside the hosted engine.
Troubleshooting
"ffmpeg was not found on PATH" — install it; the error names the command for your platform. Image tools are unaffected.
upscale_image fails with "UPSCAYL_BIN_PATH is not set" — expected if you
have not installed Upscayl. Use upscale_image_fast or upscale_image_auto.
An operation says a limit was exceeded — the message names the variable and its current value. Raise it if the file is legitimate.
AVIF conversion fails — your Pillow build has no AVIF encoder. Run
mct capabilities to see what it can write.
A GIF request is refused for frame count — fps × duration was too high.
GIF is a poor format above a few hundred frames; lower one of them.
Something failed and the message is short — that is deliberate. Re-run
with MCT_LOG_LEVEL=verbose or --log-level verbose for the underlying log.
Files appear in an unexpected place — set MCT_OUTPUT_DIR. Run from a
checkout, the default is output/ inside the repository, preserved from before
2.0; installed as a package it is output/ under the current directory.
What this server can actually do
The expensive question about an MCP server is not what it promises but what it can do on your machine: which credentials it can touch, where it connects, what it runs. Answering that means reading the source, and most people will not.
On every push, mcp-vet from the same account audits this server from source and writes the whole report into the job summary. Today's verdict: MEDIUM (it spawns external processes - a real and documented capability). The gate closes at HIGH and above — and it also closes if the tool itself could not run, because "I could not look" should not read as green.
Auditing our own server with our own tool had a side effect worth recording: adding this job surfaced a real false positive in mcp-vet, which was fixed. A tool nobody runs stays right by default.
Limitations
Stated rather than hidden:
upscale_imageneeds a discrete GPU. Measured on Intel integrated graphics: a single small icon reached 32% after seven minutes and did not finish. This is not a bug and it is not being fixed — Vulkan-based Real-ESRGAN needs real hardware.upscale_image_autowill not select it unless a discrete GPU is detected.FSRCNN is not Real-ESRGAN. It sharpens edges; it does not invent texture. Nothing in this project claims otherwise.
compare_imagesis not forensic. The similarity score is an average channel difference on 64×64 thumbnails. It is a "same picture?" hint, not evidence.Presets are a convenience, not a certification. No platform's current requirements are encoded here and platform requirements change.
generate_image_freedepends on a free public service with no availability or privacy guarantee. If it changes or disappears, nothing else here is affected.Model licences are not all verified. Where one was not confirmed against a primary source,
list_background_modelssaysnot verifiedrather than guessing.This is not a sandbox. See
SECURITY.md.
Licensing
This repository is MIT. That covers this project's code and nothing else.
Model weights, external binaries and dependencies carry their own terms — and
one commonly-reachable rembg model is non-commercial. See
THIRD_PARTY.md before assuming MIT applies to what a tool
hands you.
More from this ecosystem
local-notes-search-mcp — ask your own files a question, with no network
nvidia-nim-mcp — seven MCP tools on NVIDIA NIM's free tier
voice-io-mcp — speech in and out, needing no API key
mcp-vet — audits an MCP server's source before you install it
All of them in one searchable page: furkiozknn.github.io — each card is generated from that repository's own project-meta.json.
Available Tools
8 toolsconvert_formatA
Convert an image to another format (png, jpg, webp). Flattens transparency onto white when converting to jpg.
Inputs: image_path (required), target_format (required). Returns: result
generate_image_freeB
Generate an image from a text prompt via Pollinations.ai - genuinely free, no API key or signup required.
Inputs: prompt (required), seed, width, height. Returns: result
remove_backgroundA
Remove the background from an image, saved as a transparent PNG. CPU-only (ONNX via rembg), no API key or GPU needed.
Inputs: image_path (required). Returns: result
resize_imageB
Resize an image with high-quality Lanczos resampling. If keep_aspect is true, fits within width x height without distorting.
Inputs: width (required), height (required), image_path (required), keep_aspect. Returns: result
upscale_imageA
Upscale an image with real-ESRGAN via Vulkan (reuses Upscayl's bundled binary/models). Tested and confirmed CORRECTLY SLOW to the point of impracticality on Intel integrated graphics (minutes for a single small icon) - only use this if the machine has a real discrete GPU; otherwise prefer generate_image_free or accept the wait.
Inputs: image_path (required), model, scale. Returns: result
video_thumbnailB
Grab a single frame from a video as a PNG thumbnail. timestamp is HH:MM:SS.
Inputs: video_path (required), timestamp. Returns: result
video_to_gifB
Convert a video clip to an optimized GIF using a two-pass palette for better quality/size.
Inputs: video_path (required), fps, start, width, +1 more. Returns: result
video_trimA
Trim a video without re-encoding (fast, lossless cut on keyframe boundaries).
Inputs: start (required), duration (required), video_path (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct media operation—image generation, upscaling, background removal, resizing, format conversion, video thumbnail extraction, GIF conversion, and trimming. No two tools have overlapping responsibilities, making selection straightforward.
Most image tools follow a clear verb_noun pattern (upscale_image, remove_background, resize_image), but the video tools diverge with patterns like video_thumbnail and video_to_gif. Names are readable and consistently lowercase snake_case, but the naming convention is not uniform across the set.
Eight tools is a well-scoped size for a creative media utility server. Each tool earns its place by covering a distinct, practical task without redundancy or unnecessary bloat.
The toolkit covers image generation, common image editing workflows, and core video conversions including thumbnails, GIFs, and trimming. Minor gaps such as cropping or more advanced video encoding exist, but the main creative workflows are well supported.
Related MCP Connectors
AI-powered image processing via GPU. Remove backgrounds and upscale images (2x/4x) directly from any MCP client. OAuth 2.1 authenticated, returns processed images inline with download links. Free credits on signup at maskr.io.
Hosted MCP server for AI photo editing: nothing to install, no desktop photo editor needed.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
Hosted MCP tools for FFmpeg-style video and audio processing through FFMPEG API.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA lightweight MCP server for image processing and cloud uploads that automates resizing, converting, optimizing, and uploading images to services like AWS S3, Cloudflare R2, and Google Cloud Storage.25 npm18MIT
- AlicenseAqualityDmaintenanceAn MCP server for image and video processing that allows AI assistants to resize, convert, compress, and analyze media files locally without API keys. It supports a wide range of formats and provides tools for tasks such as metadata removal, frame extraction, and video conversion.13124 PyPI5MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for generating, editing, and processing images via multiple providers including Kilo, OpenRouter, OpenAI, and Gemini, with local tools for background removal, resizing, and cropping.16 npm3MIT
- AlicenseAqualityDmaintenanceLocal image processing MCP server providing background removal, stock media search, resize, format conversion, and collage creation.5MIT