dither-mcp

Color with character. Local image dithering for your agent.

dither-mcp is a local-first Model Context Protocol server for image dithering. Your agent can generate random styles, inspect images, compare treatments, and save recipes. The new MCP Apps studio adds image controls inside supported MCP hosts. One Go binary provides the same image pipeline through MCP and the CLI.

Moon Garden original → Atkinson / six-color clay palette / 2× pixels. Local Go programs generated the artwork and dithered treatments.

Try random styles · Open the studio · Connect your agent · Explore the showcase · Watch the demos · Read the specifications

Website · MCP Apps guide · Source code · Website source

What your agent can do

The toolkit provides 18 tools with typed inputs, 3 resources, and 3 prompts. It includes 41 dithering algorithms, 256 curated palettes, and custom palettes. It also supports image adjustments, masks, retro effects, comparison sheets, batch renders, motion, and print exports. Tools return structured results. Artifact-producing tools also return local paths and SHA-256 digests. Named favorites return a stable ID and recipe. Image artifacts include dimensions.

Image processing stays in your configured workspace, with source files and artifacts under your control. Your connected MCP host receives tool results and controls which information reaches its model.

Related MCP server: text2d

Try a random style

Ask your agent: “Open this image in the studio. I want to try random looks.” Select Random style above the preview, then keep clicking until something catches your eye. Went past a favorite? Use Undo or Redo, or select it under Recent looks and choose Restore look. The studio keeps 20 recently used looks, including your starting preview and manual refinements. New experiments keep other recent looks available.

For example: try three random looks, select Undo to return to the second, then enter Moonlit paper under Favorites and select Save favorite. To compare an older look, choose its algorithm, palette, and seed label in Recent looks and select Restore look.

History lasts for this studio session. Restoring re-previews the complete settings against the current source and mask. Named favorites survive closing the studio and are shared by sessions using the same workspace.

For API-driven iteration, call dither_random_style with {} for a fresh look or {"seed":42} for a repeatable one. It returns {seed, recipe} without reading an image or creating a file. Pass its palette and options to dither_render or dither_studio. Keep a named look with dither_favorite_save.

./bin/dither-mcp call --root . dither_random_style '{}'
./bin/dither-mcp call --root . dither_random_style '{"seed":42}'

Seeds 42, 314, and 2026, left to right. Same source, 320-pixel width, and 2× pixel grid.

Reproduce these images and save their recipes with the dependency-free example script, using Node.js 20.19 or later:

make build
node examples/random-styles.mjs docs/assets/source/moon-garden.png output/random-styles 42 314 2026

Use a new output directory on another run. The script prints each selected algorithm, palette, artifact path, and digest. Replay a saved recipe:

./bin/dither-mcp render --root . \
  --input docs/assets/source/moon-garden.png \
  --recipe output/random-styles/seed-42.json --output output/replayed-42.png

Seeds reproduce selections within the current engine and catalog version. Save the full recipe to retain its settings for later reuse. See the exact API and preview examples.

Keep named favorites across sessions

After a preview succeeds, enter a name under Favorites and select Save favorite. Open another studio on the same workspace, choose the saved name, and select Load favorite. Refresh discovers favorites added by another client. Loading previews the saved settings on the current source before changing your controls. Undo can return to the look you had before loading.

Favorites preserve custom colors, dimensions, crop, masks, and effects. They live in .dither/favorites/ under the server's configured workspace, shared by the MCP API and studio. They contain settings, not images or source paths. Use the same workspace to find them later; copy the directory to carry the library to another workspace. Save recipe remains available for individual portable JSON files.

Names are case-sensitive, trimmed, and limited to 80 Unicode characters without control characters. Existing names cannot be replaced; save a revised look under a new name. Loading requires a compatible source and, for image-mask recipes, a current external mask. Geometry is preserved, so incompatible crops or preview dimensions report an error and retain your edits.

Try the executable example, which saves, discovers, and reloads a favorite through separate CLI processes, then checks identical preview and PNG bytes:

make build
node examples/favorites.mjs docs/assets/source/moon-garden.png 'Moonlit paper' output/moonlit-paper.png
./bin/dither-mcp call --root . dither_favorites_list '{}'

Use a new name and PNG destination when repeating the example. MCP clients use dither_favorite_save with {name, recipe}, dither_favorites_list with {}, and dither_favorite_load with the returned {id}. See the named-favorites API example and limits.

An image studio inside your chat

Actual studio connected to the local Go server through the official MCP Apps bridge. Bayer 8×8 / six extracted colors / “Warm press” favorite.

Ask your agent to open dither_studio for a local image. In a host that supports MCP Apps and local stdio servers, the tool opens an interactive view beside the conversation.

Start with the Random style button above the image. Each click generates and previews a new palette, algorithm, and treatment. Click again to explore another look; the newest click wins. Your crop, mask, dimensions, and pixel size stay in place. Use Undo, Redo, or Recent looks to revisit a successful preview. Nothing is saved until you choose Save favorite, Save image, or Save recipe.

To refine a look manually, choose an algorithm and palette, adjust the image, and select Apply preview. Zoom in to examine the pixels and inspect the palette swatches. The studio uses all 41 algorithms and 256 palettes, with custom colors and the shared engine options available through the tool.

To build a palette from your image, choose a color count and select Extract colors. The studio uses the complete normalized source before crop, tone, and mask settings. It puts the colors into your custom palette. Select Apply preview to see them, then save the accepted result.

Previews run in memory and create no file. Omitted dimensions fit within 512 × 512 pixels without enlarging the source. Every preview stays within 1,024 pixels per axis and 2 MiB PNG. Choose Preview, Source, or Custom dimensions for export, then enter a new relative output path. Preview size reproduces the accepted settings. Source size uses the upright image dimensions after cropping. Custom size requires both dimensions. A different resolution can change the dither pattern. The studio preserves all other settings and checks source and mask fingerprints before saving. The filename extension selects the output format.

Select Save recipe to keep the accepted treatment in a new relative .json file. It saves the preview's exact colors, dimensions, and advanced settings. Image export dimensions do not change the recipe. Reuse image-mask recipes with an external mask file; source and mask paths are not stored.

The Go binary bundles the complete app and official MCP Apps SDK. It keeps the stdio setup and needs no runtime Node.js process, CDN, or external asset service. Hosts without Apps support receive the PNG preview and structured JSON.

The studio is verified in MCP Inspector 2.10.1 and the included embedding host. The host guide records the exact checks and versions. Read the MCP Apps guide and host setup and compatibility.

To embed the studio in your own application, use the supported AppBridge example. It connects a browser view to the local Go server over stdio. GitHub Pages serves the separate showcase; interactive local processing needs a host and backend.

Supported files

Still-image tools use the first GIF frame. To process every GIF frame, use dither_animate with effect: "source". GIF animation defaults to this mode. It preserves frame composition, disposal, delays, and loop count.

Generated animations start from one still image. Print separation supports at most 16 inks.

Video processing requires --allow-video and local FFmpeg and ffprobe executables. It processes short, bounded segments and exports video without audio. Available input decoders and output codecs depend on your FFmpeg build.

Still-image tools apply all eight EXIF orientations before cropping and resizing. They convert supported embedded RGB ICC profiles to sRGB and preserve alpha. Untagged RGB images use sRGB.

Read the format guide for profile coverage, file behavior, codec requirements, and video limits.

Stored pixel samples appear at left. Actual service previews appear at right. Reproduce this original chart and inspect its results.

Connect your agent

Build from this source checkout with Go 1.27:

git clone https://github.com/lennrt/dither-mcp.git
cd dither-mcp
go mod download
go build -o bin/dither-mcp ./cmd/dither-mcp
./bin/dither-mcp catalog

For an MCP client that uses an mcpServers configuration, supply absolute paths:

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

1. Reconnect the client.

2. Ask it to inspect an image.

3. Ask it to open the studio, then try Random style.

Paths in tool calls are relative to --root. The server exchanges MCP messages on stdin/stdout and sends diagnostics to stderr.

See the MCP guide for schemas, examples, resources, prompts, and limits. The CLI guide documents direct use of the same operations.

Explore the gallery

The Moon Garden is a waxy-leaf plant in a fluted ceramic pot, with textured stones and a suspended golden sphere. A deterministic Go ray tracer creates its light, shadows, veins, grain, and mineral bands. Each algorithm converts these surfaces into a distinct pixel pattern.

Left to right, top to bottom: Atkinson · Floyd–Steinberg · Bayer 8×8 · dot screen 8 · blue noise · Riemersma. Same crop, two warm colors, fixed seed.

Atkinson / Game Boy · Floyd–Steinberg / custom ember · Bayer 4×4 / CGA.

Every palette. A new possibility.

The catalog includes 256 palettes across 16 categories. Names, descriptions, tags, color counts, and hex values help your agent find a palette. Every palette has a stable ID. Use that ID in renders and recipes.

The categories are:

• Retro, terminal, interface, and print.

• Duotone, botanical, landscape, and ocean.

• Mineral, seasonal, neon, and pastel.

• Food, cosmic, architecture, and neutral.

The twelve images use the same source and Floyd–Steinberg settings. View the complete 256-palette atlas. Read the palette guide for descriptions, sources, and exact colors.

./bin/dither-mcp palettes --category botanical \
  --min-colors 4 --max-colors 6 --limit 8

./bin/dither-mcp palettes --query 'oat ink'

./bin/dither-mcp render --root . \
  --input docs/assets/source/moon-garden.png \
  --output oat-garden.png \
  --algorithm floyd-steinberg --palette oat-and-ink \
  --width 960 --pixel-scale 2

Use a preset or supply 2–256 unique hex colors. Custom palettes are explicit recipe inputs. Extract a palette from a local image when you want the image’s own colors to guide the result. Extraction scans every visible pixel, so small accents and periodic stripes contribute. A bounded histogram and median cut reduce those colors to your requested count.

./bin/dither-mcp render --root . \
  --input docs/assets/source/mineral-nocturne.png \
  --output mineral.png \
  --algorithm floyd-steinberg \
  --colors '#251d32,#ab4e3b,#e6ad62,#f0e7d3' \
  --width 960 --pixel-scale 2

Wave / 24 frames / 12 fps. Reproduce the artwork and recipes.

Explore the dither-mcp website for the MCP Apps studio, a keyboard-accessible comparison slider, actual algorithm previews, a searchable palette explorer, palette studies, and recorded demos. The website source lives in a separate repository and supports GitHub Pages.

Make a reproducible recipe

Start with an inspection and a comparison sheet:

./bin/dither-mcp inspect --root . \
  --input docs/assets/source/moon-garden.png

./bin/dither-mcp compare --root . \
  --input docs/assets/source/moon-garden.png \
  --output comparison.png \
  --algorithms atkinson,floyd-steinberg,bayer-8 \
  --palette sepia --width 320

To compare colors with the same texture, use a palette shortlist:

./bin/dither-mcp compare --root . \
  --input docs/assets/source/moon-garden.png \
  --output palette-studies.png \
  --palettes oat-and-ink,gameboy,sepia --algorithm atkinson --width 320

Left to right: Oat and Ink · Game Boy · Sepia. Each cell reports its palette, algorithm, and exact rectangle.

Compare either palettes or algorithms, with at most 12 candidates. Palette mode uses shared inline options and excludes a common palette, custom colors, and saved recipes. Each candidate can then be rendered separately.

Save the settings in a versioned recipe. Use that recipe to render the image:

./bin/dither-mcp call --root . dither_recipe_save '{
  "output": "garden.recipe.json",
  "recipe": {
    "version": 1,
    "palette": "gameboy",
    "options": {
      "algorithm": "atkinson",
      "width": 960,
      "pixel_scale": 2,
      "seed": 42
    }
  }
}'

./bin/dither-mcp render --root . \
  --input docs/assets/source/moon-garden.png \
  --output garden.png --recipe garden.recipe.json

Recipes keep image settings portable across source files and destinations. A render result includes the resolved recipe and artifact digest. Explicit seeds make noise, glitch, and animation reproducible. For a saved recipe, apply the complete configuration. For a new treatment, supply inline settings.

A new output path preserves your earlier work. Give each variation a separate name.

The toolkit

The engine preserves source alpha. Diffusion stops at transparent pixels and mask boundaries. Regions outside the mask retain adjusted source colors. Post-effects can introduce colors beyond the selected palette. See the feature matrix for precise coverage and the architecture for pipeline order and boundaries.

See it run

Charmbracelet VHS recorded these local demos. They use the binary and original artwork from this checkout.

Watch the render clip.

Watch the comparison and animation clip.

Watch the MCP clip. The scripted Go client connects to the real stdio server and is ready to replay locally.

Watch the palette discovery clip. Search, select, render, and keep the resulting recipe.

Recreate the source art and gallery with ./scripts/showcase.sh. Record the terminal clips with ./scripts/showcase-record.sh. The showcase guide lists prerequisites, exact recipes, asset provenance, and recording checks.

Specified and verified

OpenSpec records the requirements, scenarios, and implementation changes. Quint models describe input normalization, quantization, artifact publication, and bounded palette discovery. The formal models abstract pixel values, operating-system behavior, and process execution. Their checks complement implementation tests.

make verify
make spec-install
make spec-check

The specification tools are development-only dependencies and require Node 20.19+ and pnpm. See testing for the checks, their recorded outcomes, and what they establish. Security explains the filesystem boundary, limits, and optional FFmpeg integration.

License and credits

The project uses the MIT license. See LICENSE and third-party notices. Original showcase artwork and recordings use the same license. The sources guide lists algorithm references and inspiration. It also records the references and platform credits for classic techniques and retro palettes.