dither-mcp

Local files. Agent tools. 41 algorithms.

Color with
character.

Find a look worth keeping. Try a random style, revisit it with Undo, and save a named favorite for your next image. Your local studio brings 41 algorithms and 256 palettes into your chat.

One Go binaryMCP Apps + stdioLocal processing
Fig. 001 / Moon Garden6 colors
Moon Garden rendered with Atkinson dithering in six clay and paper colors Original ray-traced still life of a waxy-leaf plant, ceramic pot, textured stones, and a golden sphere OriginalAtkinson
50%
Atkinson · Clay · 2× pixels
Random → Undo → Favorite18 agent toolsExact recipesLocal image processing

Try the possibilities

One image.
Another possibility.

Keep clicking. Go back when something catches your eye. These sample looks pair real engine output with the exact recipe that made it.

This sample uses pre-rendered Moon Garden images. There is no image upload or browser image processing. Open the local studio to work with your own files.

Moon Garden rendered with Diamond screen dithering in the Game Boy green palette

Diamond screen / Game Boy green

4 colors · Seed 42

A new color and texture

Recent samples

Diamond screen / Game Boy green. Seed 42. Sample ready.

Recent samples last for this visit and reset when you reload.

The downloads match the displayed sample. Reuse the recipe with the Moon Garden source image and the same engine version.

Keep a look for your next session. In the real studio, give an accepted preview a name and select Save favorite. Favorites persist in your workspace and are shared with your agent through the MCP API.

Explore without losing your place. The real studio keeps 20 recent looks, including manual refinements. Undo, Redo, and Restore look re-preview complete settings on your current image. See the favorites workflow.

MCP Apps / Local studio

An image studio,
inside your chat.

Let your agent open the image. Try a new treatment in one click, return to a promising look, and keep the settings you love.

Actual PR #2 preview studio showing Random style, recent looks, Favorites, Moon Garden, Discard edits, and image and recipe saves
Actual PR #2 preview studio · local Go server · official MCP Apps bridge.Random · Undo · Favorites

Ask your agent

“Open this image in the studio. I want to try random looks and keep my favorites.”
  1. Try a random style.

    One click chooses a palette, algorithm, and treatment, then previews it. Your crop, mask, dimensions, and pixel scale stay in place.

  2. Go back to the one you liked.

    Undo, Redo, or select a recent look. The studio keeps 20 accepted previews for this session, including your starting settings and manual edits.

  3. Name it. Keep it.

    Save favorite stores the exact recipe in your workspace. Reopen the studio or ask your agent to load it later, on a compatible image and mask.

Read the studio guide

Export exactly what you chose. Save a PNG at preview size for matching pixels, or choose source or custom dimensions. Save recipe keeps the accepted colors, geometry, masks, and effects as portable JSON. A different export resolution can change the dither pattern.

Your files stay under your control. Previews create no file. Image saves check that the source and mask still match the preview and never replace an existing destination. Repeated Random clicks keep the newest result; canceled or late previews cannot replace it.

Your workspace. Your next image. Named favorites survive restarts in .dither/favorites/. They contain settings, without image or source paths. Keep a compatible external mask when reusing an image-mask recipe.

Use a host that supports MCP Apps and local stdio servers. The current workflows are verified in the included local embedding host. Other hosts receive a PNG and structured JSON. See host compatibility and earlier Inspector checks.

Bring the studio into your app. The supported embedding example uses the official MCP Apps bridge, a local backend, and your chosen workspace. Build with the embedding guide.

The complete studio is bundled with the Go binary. This website presents static samples and screenshots; processing your own files requires a local MCP host.

Playwright captured the actual studio through the local MCP Apps test host. These PR #2 preview captures also show Discard edits. Desktop and mobile checks cover random iteration, history, persistent favorites, keyboard previews, and saves. Preview defaults fit within 512 × 512 pixels; each stays within 1,024 pixels per axis and 2 MiB PNG.

A look ahead / PR #2 preview

More room to try.
Less work to repeat.

Ten changes carry a promising look from comparison to export. They are available in open PR #2, not yet merged into the main branch.

These samples and studio captures use preview commit 26a6707. Build that revision to try the controls and commands below.

Build the preview in a fresh checkout
git clone https://github.com/lennrt/dither-mcp.git dither-mcp-preview
cd dither-mcp-preview
git checkout 26a670707d114486c2396b7fe827a39cf637c7aa
go build -o bin/dither-mcp ./cmd/dither-mcp

Requires Go 1.27. The render examples below use this binary and the Moon Garden source included in the checkout.

From candidate to finished file

01 / Keep the comparison

Take one cell with you.

Each cell returns its processing recipe and rendered dimensions. Replay it on the same source and required mask to reproduce pixels before output encoding.

02 / Area resizing

Give small details a fair share.

Area averages source-pixel coverage before dithering. Exact integer sums round half values up, including alpha at GIF’s transparency cutoff. Bilinear remains the default.

03 / BMP export

A simple file for older tools.

Export uncompressed 24-bit BMP for compatible image workflows. Transparency composites onto white.

Download actual BMP
04 / TIFF export

Keep the color and alpha values.

Lossless TIFF stores uncompressed, unassociated 8-bit RGBA. It uses default 72 DPI tags. Custom DPI remains PNG-only.

Download actual TIFF
Synthetic 640 by 320 source with repeating white and black two-pixel vertical stripes
Source · 640 × 320 · 50% white
The stripe stress case reduced to 160 by 80 with Bilinear then Bayer 4 by 4 mono dithering; all pixels become black
Bilinear · 160 × 80 · 0% white
The same stripe stress case reduced with Area and identical dither settings; half the output pixels remain white
Area · 160 × 80 · 50% white
A synthetic stress case: two-pixel stripes reduced 4× with the same monochrome palette and Bayer 4×4 algorithm. Area retains the average tone here; results depend on the source. It averages display-space RGB with alpha weighting. Download the source. Read the export limits.
Moon Garden rendered with Area resizing, Bayer 4 by 4, and the Terracotta Courtyard palette

One look. Ready for the next tool.

The BMP and TIFF downloads share these 320 × 160 pixels and the same recipe. This opaque sample demonstrates format interchange. The studio also supports TIFF alpha.

PNG reference ↓Exact recipe ↓Source image ↓

Compare pixels before encoding. JPEG blocks can cross cell boundaries. GIF chooses a palette for the whole sheet, so a separately encoded cell can differ. BMP composites alpha against white. Use PNG or TIFF for pixel comparisons with full alpha.

Discover what each export keeps. The catalog now describes every still output’s MIME type, representation, and alpha behavior. BMP reports image/bmp with a white matte. TIFF reports image/tiff with full alpha.

Runs you can account for

05 / Clear CLI options

Catch a conflict before rendering.

CLI flags and JSON options can set different fields. Setting the same field twice reports an error, including explicit zero or false values.

06 / Complete batch results

Know where the batch stopped.

After mid-run cancellation, every admitted batch item keeps an indexed result. Earlier files remain available; remaining items report cancellation.

Stay in the creative flow

07 / Discard edits

Find your way back.

Restore the last accepted settings for this host input, even after unfinished JSON or colors. A new input needs a successful preview first.

08 / Proportional exports

Choose a size. Keep the shape.

Custom export starts at the preview size. Lock the ratio to pair dimensions, or unlock it for another shape. Recipe settings stay intact.

09 / Keyboard previews

Try it without leaving the editor.

Press Ctrl+Enter or Cmd+Enter in custom colors or advanced JSON to apply the draft. Ordinary Enter still inserts a newline.

10 / Preserve palette edits

Your colors stay yours.

Clicking the active Custom colors tab keeps your typed colors and unfinished edits. Explore without an accidental reset.

Actual studio retaining its earlier Moon Garden preview after a simulated replacement-mask host error, with Discard edits and Save image disabled

Current input / safe recovery

A new input needs a new preview.

Reusing a source path still starts a new host input. Failed or canceled replacement previews keep the new settings and mask. Discard edits becomes available after that input has an accepted preview.

Correct the input, then apply a successful preview before restoring settings or saving.

Actual bundled studio in the local test host, with a simulated host mask error. The earlier image remains visible while Discard edits and Save image stay disabled. Select the screenshot to view it full size.

Ask your agent / PR #2

“Compare three treatments. Save the second cell’s exact recipe, then render it as a small TIFF using Area resizing.”

Save cells[1].recipe with dither_recipe_save. Reuse the current source and any required mask.

Follow the comparison handoff
Preview revision / separate option fields
# Shrink with Area and export lossless RGBA TIFF.
./bin/dither-mcp render --root . \
  --input docs/assets/source/moon-garden.png \
  --output small-print.tiff \
  --palette gameboy --algorithm atkinson \
  --width 320 --options '{"resize_filter":"area"}'

# Use another new output path for an opaque BMP.
./bin/dither-mcp render --root . \
  --input docs/assets/source/moon-garden.png \
  --output small-print.bmp \
  --width 320 --options '{"resize_filter":"area"}'

Local checks on November 1, 2026 covered 65 UI tests, 24 studio browser workflows, and the shared Go service. Finite models and local Chromium checks do not establish compatibility with every platform or host. Inspect the verification record. Read the preview studio guide.

Supported files

Images and video

Still-image tools apply orientation and supported color profiles before dithering. Local FFmpeg handles video containers and codecs.

WorkflowInputOutput
Still imagesPNG, JPEG, GIF, WebP, BMP, and TIFFPNG, JPEG, GIF, SVG, PBM, and ASCII.
PR #2 preview adds BMP and TIFF: eight output formats.
Generated animationOne supported still imageAnimated GIF or a PNG sprite sheet
GIF animationAnimated GIFAnimated GIF or a PNG sprite sheet
VideoMP4, MOV, WebM, Matroska, and AVIMP4 (H.264), WebM (VP9), GIF, or a PNG sprite sheet
Print separationOne supported still imageZIP with PNG ink plates and a JSON manifest

JPEG, PNG, WebP, and TIFF inputs can contain EXIF orientation and RGB ICC profiles. BMP V5 inputs also support embedded RGB ICC profiles. The tool applies all eight orientations and converts supported RGB profiles to sRGB. Untagged RGB images use sRGB. Still-image tools use the first GIF frame. To process all GIF frames, use dither_animate with effect: "source". GIF animation defaults to this mode and preserves source timing. Print separation supports at most 16 inks.

In the PR #2 preview, BMP uses a white matte and TIFF retains straight RGBA without compression. Both share the 32 MiB artifact limit. TIFF uses default 72 DPI tags; custom DPI remains PNG-only.

For video, start the server with --allow-video. Install local FFmpeg and ffprobe executables. The tool processes short, bounded segments without audio. Available decoders and codecs depend on your FFmpeg build.

View orientation and color normalization
Stored EXIF orientation 6 and linear RGB samples beside actual upright and sRGB service previews

02 / The color library

Every palette.
A new possibility.

Explore 256 palettes across 16 categories. Filter by category and color count. Use the palette’s exact colors in your next recipe.

Find colors in your own image. In the local studio, Extract colors scans the full normalized source before crop, masks, and effects. Small visible accents and repeating stripes contribute instead of falling between sample positions. Reducing an image to a smaller palette can still merge rare colors.

Compare colors with the texture held steady. Ask your agent to compare up to 12 named palettes using one algorithm. Each contact-sheet cell reports its palette, algorithm, and dimensions so you can replay the one you choose.

Moon Garden rendered with the same algorithm in three palettes: Oat and Ink, Game Boy, and Sepia

Loading the color library…

Page 1

Color in context

Twelve palettes. One Moon Garden.

These Floyd–Steinberg renders use the same source and settings. Choose a study to view its palette.

The Go generator creates these catalog entries, swatches, and image treatments. MCP and the CLI use the same engine.

03 / Agent workflows

Create a
reproducible recipe.

Your agent has 18 tools, three resources, and three prompts to discover, compare, render, and keep looks. Results include exact settings; image artifacts include local paths and hashes, and favorites return a stable ID.

Ask your agent
“Try a random look on this image. Keep the one I choose as Moonlit paper, so we can use it next time.”
dither_random_styledither_studiodither_favorite_savedither_favorite_load
Local CLI / same engine
# Render the image with Atkinson and Game Boy colors.
dither-mcp render \
  --root . \
  --input moon-garden.png \
  --output garden.png \
  --algorithm atkinson \
  --palette gameboy \
  --width 960 --pixel-scale 2

# Save the settings in a versioned recipe.
dither-mcp call --root . \
  dither_recipe_save '{"output":"garden.recipe.json",
    "recipe":{"version":1,"palette":"gameboy",
      "options":{"algorithm":"atkinson",
        "width":960,"pixel_scale":2}}}'

Process images locally

The tool reads images and writes artifacts in your configured workspace. It processes each image locally.

Combine image settings

A recipe combines an algorithm, palette, mask, adjustments, and retro effects. Each operation adds its animation or export settings.

Check the specifications

OpenSpec defines behavior. Quint models input normalization, quantization, artifact publication, palette discovery, studio interactions, and guarded exports. Go and JavaScript tests check the implementation.

04 / Animation

Create a
looping animation.

The animation tool generates loops from still images. It also processes all frames of a source GIF. Both workflows export GIFs or PNG sprite sheets.

Watch the terminal demos
Dithered botanical still life with a wave animation
Wave / 24 frames / 12 fps

05 / Recorded commands

From request
to pixels.

Charmbracelet VHS recorded these local demos. Each demo runs the binary with the artwork above.

Choose a palette. Render a print.

The CLI inspects the local source and creates an Atkinson render.

Run a local MCP session.

The Go client discovers the toolkit through stdio. It compares treatments, previews an artifact, saves a recipe, and checks its digest.

Find colors for your next image.

The CLI filters palettes by category and color count. It searches the 256-palette library and renders an image with Oat and Ink.

06 / Connect your agent

Connect your agent
to dither-mcp.

  1. Build the binary locally.
  2. Add it to your MCP client.
  3. Set --root to the folder that contains your images and outputs.
  4. Ask your agent to open dither_studio in a host with MCP Apps support.

Build from the source checkout

go build -o bin/dither-mcp ./cmd/dither-mcp
./bin/dither-mcp catalog

MCP client configuration

{
  "mcpServers": {
    "dither": {
      "command": "/absolute/path/bin/dither-mcp",
      "args": ["mcp", "--root", "/path/to/images"]
    }
  }
}

Build with Go 1.27. The MCP Apps studio is bundled with the binary and needs no runtime Node.js process. Video processing also uses a local FFmpeg installation. The server sends images and tool results to your connected MCP client. Get the source and setup guide on GitHub.