Skip to main content
Glama

mini-creative-toolkit

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.jpg

Your 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

A terminal: mct inspect shows has_exif True, mct strip-metadata rewrites the file, a second inspect shows has_exif False; then a scripted MCP session lists 23 tools and repeats the calls, every reply carrying network none

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, generate_image_free, sends your prompt to a third party

You give an agent file access and want every tool to declare what it needs (list_capabilities)

You need Real-ESRGAN quality without a discrete GPU. upscale_image stalled on integrated graphics; upscale_image_fast (FSRCNN) is the CPU path

You have a folder of images: mct batch photos/*.jpg --operation optimize, one bad file never loses the batch

You expect a sandbox. It runs with your permissions; set MCT_ALLOWED_ROOTS for a model you do not trust

You want the answer to "what can this machine run?" before a job (mct capabilities)

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

list_capabilities

Every tool's requirements and whether this machine can currently run it

inspect_media

Format, dimensions, codecs, duration, fps, metadata presence

list_background_models

rembg models with size, speed, and licence status

list_presets

Built-in dimension presets

Images

Tool

Does

resize_image

Lanczos resize; fits inside the box without distorting by default

convert_format

PNG / JPEG / WebP / AVIF, with quality and lossless controls

strip_metadata

Rebuilds from raw pixels — EXIF, GPS, ICC, XMP, PNG text chunks all gone

add_watermark

Semi-transparent text at a corner or the centre

remove_background

Subject cut-out to a transparent PNG

create_contact_sheet

Tile many images into one review sheet

compare_images

Byte equality, dimensions, and a coarse similarity score

Upscaling

Tool

Does

upscale_image_fast

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×

upscale_image

Real-ESRGAN via Upscayl — best quality, needs a discrete GPU

upscale_image_auto

Picks between them and explains which and why

Video and audio

Tool

Does

video_thumbnail

One frame as a PNG

video_to_gif

Two-pass palette GIF, with frame-count guards

video_trim

Lossless stream copy, re-encoding only when the copy lands short

video_resize

Scale, always to even dimensions (H.264 requires them)

video_compress

H.264/AAC at a chosen CRF

extract_audio

mp3 or wav

Higher-level

Tool

Does

optimize_media

Inspect → choose a pipeline → apply → report every trade made

batch_process

One operation over many files, bounded concurrency, failure isolated

Hosted — the one that leaves your machine

Tool

Does

generate_image_free

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

resize_image

yes

no

no

no

yes

convert_format

yes

no

no

no

yes

strip_metadata

yes

no

no

no

yes

add_watermark

yes

no

no

no

yes

create_contact_sheet

yes

no

no

no

yes

compare_images

yes

no

no

no

yes

remove_background

yes

first run only

optional

no

per model

upscale_image_fast

yes

no

no

no

yes

upscale_image

yes

no

required

upscayl-bin

yes

upscale_image_auto

yes

no

optional

only if selected

yes

video_thumbnail

yes

no

no

ffmpeg

yes

video_to_gif

yes

no

no

ffmpeg

yes

video_trim

yes

no

no

ffmpeg, ffprobe

yes

video_resize

yes

no

no

ffmpeg, ffprobe

yes

video_compress

yes

no

no

ffmpeg, ffprobe

yes

extract_audio

yes

no

no

ffmpeg

yes

inspect_media

yes

no

no

ffprobe (AV only)

yes

optimize_media

yes

no

no

ffmpeg (video only)

yes

batch_process

yes

first run only (remove_background only)

no

per operation

yes

list_capabilities

yes

no

no

no

yes

list_background_models

yes

no

no

no

yes

list_presets

yes

no

no

no

yes

generate_image_free

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_thumbnail without ffmpeg.

  • limitations — the tool runs, on fewer inputs. inspect_media without 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 takes overwrite, because then a caller can ask it to replace an existing file. batch_process has 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 without output_path writes 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 structuredContent as 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_link to 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 --version

To 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 capabilities

That 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             # macOS

On 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/models

If 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 serve

From 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-toolkit

Older 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 at

To 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 models

Add --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 errors with 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_path to 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

MCT_OUTPUT_DIR

output/

Where generated files land

MCT_ALLOWED_ROOTS

(unset)

Restrict file access to these directories

MCT_MAX_INPUT_MB

512

Largest input file

MCT_MAX_OUTPUT_MB

1024

Largest output file

MCT_MAX_IMAGE_PIXELS

80000000

Largest image read (decompression-bomb guard) or produced (resize, upscale, contact sheet)

MCT_MAX_VIDEO_DURATION

3600

Longest video, in seconds

MCT_MAX_VIDEO_WIDTH / _HEIGHT

7680

Largest video dimensions

MCT_MAX_BATCH_ITEMS

200

Largest batch

MCT_BATCH_CONCURRENCY

4

Workers for standard operations

MCT_HEAVY_BATCH_CONCURRENCY

2

Workers for CPU-heavy operations

MCT_HTTP_TIMEOUT

60

Hosted call timeout, in seconds

MCT_MAX_DOWNLOAD_MB

64

Largest hosted response

MCT_SUBPROCESS_TIMEOUT

900

ffmpeg / Upscayl timeout, in seconds

MCT_LOG_LEVEL

normal

quiet, normal or verbose

MCT_LEGACY_STRING_RESULTS

false

Return a bare path string, as before 2.0

MCT_CACHE_MODELS

true

Keep rembg sessions and FSRCNN networks in memory between calls; 0 frees the memory

MCT_INLINE_PREVIEWS

1

Attach a 512 px preview to image results; 0 switches previews off

MCT_PRESETS_IMAGE_<NAME> / MCT_PRESETS_VIDEO_<NAME>

—

Override a preset, e.g. 1200x1200

MCT_FORCE_GPU / MCT_FORCE_NO_GPU

(unset)

Skip discrete-GPU detection (which only decides what upscale_image_auto picks)

UPSCAYL_BIN_PATH / UPSCAYL_MODELS_PATH

(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=True anywhere. A test parses the AST of every module to enforce it. Commands are argument lists; binaries come from shutil.which.

  • Every non-path value that reaches argv is shape-constrained. Timestamps must match a digits-and-colons grammar much narrower than ffmpeg's own, so a value like -ss or -i cannot 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=true the commit refuses a name that already exists, even one that appeared mid-run. Your input is replaced only if you name it as output_path and pass overwrite=true.

  • Dependencies stay quiet too. onnxruntime (under rembg) ships with telemetry on; the package sets ORT_DISABLE_TELEMETRY=1 before it can load, so the network: none in a payload also covers what a dependency would have sent.

  • Sizes are bounded both ways. MCT_MAX_IMAGE_PIXELS applies 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 weights

Two rules hold the shape:

  1. Business logic exists once. server.py and cli.py both call tools/. A validation fix lands in both surfaces at the same moment.

  2. 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 pytest

405 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_image needs 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_auto will 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_images is 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_free depends 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_models says not verified rather 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

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 tools
convert_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

    A3.7/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers